woclaw-hub 0.1.0

package/Dockerfile

@@ -0,0 +1,41 @@
+FROM node:18-alpine
+
+WORKDIR /app
+
+# Install build dependencies for better-sqlite3
+RUN apk add --no-cache \
+    python3 \
+    make \
+    g++ \
+    && rm -rf /var/cache/apk/*
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci --only=production
+
+# Copy source (pre-built)
+COPY dist ./dist
+
+# Create data directory
+RUN mkdir -p /data && chown -R node:node /data
+
+# Expose ports
+EXPOSE 8080 8081
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:8081/health || exit 1
+
+# Run as non-root user
+USER node
+
+ENV NODE_ENV=production
+ENV HOST=0.0.0.0
+ENV PORT=8080
+ENV REST_PORT=8081
+ENV DATA_DIR=/data
+ENV AUTH_TOKEN=change-me-in-production
+
+CMD ["node", "dist/index.js"]

package/README.md

@@ -0,0 +1,173 @@
+# WoClaw Hub
+
+WebSocket relay server for OpenClaw multi-agent communication.
+
+## Quick Start
+
+### Using Docker
+
+```bash
+# Build
+docker build -t woclaw/hub .
+
+# Run
+docker run -d \
+  --name woclaw-hub \
+  -p 8080:8080 \
+  -p 8081:8081 \
+  -v /path/to/data:/data \
+  -e AUTH_TOKEN=your-secure-token \
+  --restart unless-stopped \
+  woclaw/hub
+```
+
+### From Source
+
+```bash
+cd hub
+npm install
+npm run build
+npm start
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | 8080 | WebSocket server port |
+| `REST_PORT` | 8081 | REST API port (future) |
+| `HOST` | 0.0.0.0 | Bind address |
+| `DATA_DIR` | /data | SQLite database directory |
+| `AUTH_TOKEN` | change-me | Authentication token |
+| `CONFIG_FILE` | - | JSON config file path |
+
+## WebSocket API
+
+### Connect
+
+```javascript
+const ws = new WebSocket('ws://localhost:8080?agentId=vm151&token=your-token');
+```
+
+### Send Message
+
+```javascript
+ws.send(JSON.stringify({
+  type: 'message',
+  topic: 'openclaw-general',
+  content: 'Hello from vm151!'
+}));
+```
+
+### Join Topic
+
+```javascript
+ws.send(JSON.stringify({
+  type: 'join',
+  topic: 'openclaw-general'
+}));
+```
+
+### Leave Topic
+
+```javascript
+ws.send(JSON.stringify({
+  type: 'leave',
+  topic: 'openclaw-general'
+}));
+```
+
+### Write to Shared Memory
+
+```javascript
+ws.send(JSON.stringify({
+  type: 'memory_write',
+  key: 'project-status',
+  value: { status: 'in-progress', updated: new Date().toISOString() }
+}));
+```
+
+### Read Memory
+
+```javascript
+ws.send(JSON.stringify({
+  type: 'memory_read',
+  key: 'project-status'
+}));
+```
+
+### List Topics
+
+```javascript
+ws.send(JSON.stringify({
+  type: 'topics_list'
+}));
+```
+
+### Get Topic Members
+
+```javascript
+ws.send(JSON.stringify({
+  type: 'topic_members',
+  topic: 'openclaw-general'
+}));
+```
+
+## Server Responses
+
+```javascript
+// New message
+{ "type": "message", "topic": "...", "from": "vm151", "content": "...", "timestamp": 1234567890 }
+
+// Join confirmation
+{ "type": "join", "topic": "...", "agent": "vm151", "timestamp": 1234567890 }
+
+// Leave notification
+{ "type": "leave", "topic": "...", "agent": "vm151", "timestamp": 1234567890 }
+
+// Message history (on join)
+{ "type": "history", "topic": "...", "messages": [...], "agents": [...] }
+
+// Memory update broadcast
+{ "type": "memory_update", "key": "...", "value": "...", "from": "vm151", "timestamp": 1234567890 }
+
+// Memory value response
+{ "type": "memory_value", "key": "...", "value": "...", "exists": true, "updatedAt": ..., "updatedBy": "vm151" }
+
+// Topics list
+{ "type": "topics_list", "topics": [{ "name": "...", "agents": 3 }] }
+
+// Topic members
+{ "type": "topic_members", "topic": "...", "agents": ["vm151", "vm152"] }
+
+// Error
+{ "type": "error", "code": "...", "message": "...", "timestamp": 1234567890 }
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      WoClaw Hub                            │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
+│  │  Topics Mgr │  │ Memory Pool │  │    SQLite   │        │
+│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘        │
+│         │                │                │                 │
+│         └────────────────┼────────────────┘                 │
+│                          │                                   │
+│                  ┌───────┴───────┐                           │
+│                  │  WSServer     │                           │
+│                  └───────┬───────┘                           │
+└──────────────────────────┼───────────────────────────────────┘
+                           │
+         ┌─────────────────┼─────────────────┐
+         │                 │                 │
+    ┌────┴────┐       ┌────┴────┐       ┌────┴────┐
+    │ vm151   │       │ vm152   │       │ vm153   │
+    │ (p14)   │       │         │       │         │
+    └─────────┘       └─────────┘       └─────────┘
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "woclaw-hub",
+  "version": "0.1.0",
+  "description": "WoClaw Hub - WebSocket relay server for OpenClaw multi-agent communication",
+  "main": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx watch src/index.ts",
+    "docker:build": "docker build -t woclaw/hub ."
+  },
+  "dependencies": {
+    "ws": "^8.16.0",
+    "uuid": "^9.0.1"
+  },
+  "devDependencies": {
+    "@types/uuid": "^9.0.7",
+    "@types/ws": "^8.5.10",
+    "tsx": "^4.7.1",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/db.ts

@@ -0,0 +1,128 @@
+// WoClaw Database - Simple JSON File Store
+// No native compilation required!
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname } from 'path';
+import { DBMessage, DBMemory } from './types.js';
+
+export class ClawDB {
+  private dbPath: string;
+  private data: {
+    messages: DBMessage[];
+    memory: { key: string; value: string; updatedAt: number; updatedBy: string }[];
+    topics: { name: string; createdAt: number; messageCount: number }[];
+  };
+
+  constructor(dataDir: string) {
+    if (!existsSync(dataDir)) {
+      mkdirSync(dataDir, { recursive: true });
+    }
+    this.dbPath = `${dataDir}/woclaw.json`;
+    this.data = this.load();
+  }
+
+  private load() {
+    if (existsSync(this.dbPath)) {
+      try {
+        return JSON.parse(readFileSync(this.dbPath, 'utf-8'));
+      } catch (e) {
+        console.error('[ClawDB] Failed to load DB, starting fresh');
+      }
+    }
+    return {
+      messages: [],
+      memory: [],
+      topics: [],
+    };
+  }
+
+  private save() {
+    try {
+      writeFileSync(this.dbPath, JSON.stringify(this.data, null, 2));
+    } catch (e) {
+      console.error('[ClawDB] Failed to save:', e);
+    }
+  }
+
+  // Messages
+  saveMessage(msg: DBMessage): void {
+    this.data.messages.push(msg);
+    // Keep last 1000 messages per topic (simple cleanup)
+    if (this.data.messages.length > 10000) {
+      this.data.messages = this.data.messages.slice(-5000);
+    }
+    
+    // Update topic stats
+    const topic = this.data.topics.find(t => t.name === msg.topic);
+    if (topic) {
+      topic.messageCount++;
+    } else {
+      this.data.topics.push({ name: msg.topic, createdAt: Date.now(), messageCount: 1 });
+    }
+    this.save();
+  }
+
+  getMessages(topic: string, limit: number = 100, before?: number): DBMessage[] {
+    let msgs = this.data.messages.filter(m => m.topic === topic);
+    if (before) {
+      msgs = msgs.filter(m => m.timestamp < before);
+    }
+    return msgs.slice(-limit).reverse();
+  }
+
+  // Memory
+  setMemory(key: string, value: string, updatedBy: string): void {
+    const existing = this.data.memory.find(m => m.key === key);
+    if (existing) {
+      existing.value = value;
+      existing.updatedAt = Date.now();
+      existing.updatedBy = updatedBy;
+    } else {
+      this.data.memory.push({ key, value, updatedAt: Date.now(), updatedBy });
+    }
+    this.save();
+  }
+
+  getMemory(key: string): DBMemory | undefined {
+    const m = this.data.memory.find(mem => mem.key === key);
+    if (!m) return undefined;
+    return {
+      key: m.key,
+      value: m.value,
+      updatedAt: m.updatedAt,
+      updatedBy: m.updatedBy,
+    };
+  }
+
+  deleteMemory(key: string): boolean {
+    const idx = this.data.memory.findIndex(m => m.key === key);
+    if (idx >= 0) {
+      this.data.memory.splice(idx, 1);
+      this.save();
+      return true;
+    }
+    return false;
+  }
+
+  getAllMemory(): DBMemory[] {
+    return this.data.memory.map(m => ({
+      key: m.key,
+      value: m.value,
+      updatedAt: m.updatedAt,
+      updatedBy: m.updatedBy,
+    }));
+  }
+
+  // Topics
+  getTopicStats(): { name: string; messageCount: number; createdAt: number }[] {
+    return this.data.topics.map(t => ({
+      name: t.name,
+      messageCount: t.messageCount,
+      createdAt: t.createdAt,
+    }));
+  }
+
+  close(): void {
+    this.save();
+  }
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+import { WSServer } from './ws_server.js';
+import { RestServer } from './rest_server.js';
+import { ClawDB } from './db.js';
+import { Config } from './types.js';
+import { readFileSync } from 'fs';
+
+const DEFAULT_CONFIG: Config = {
+  port: parseInt(process.env.PORT || '8080'),
+  restPort: parseInt(process.env.REST_PORT || '8081'),
+  host: process.env.HOST || '0.0.0.0',
+  dataDir: process.env.DATA_DIR || '/data',
+  authToken: process.env.AUTH_TOKEN || 'change-me-in-production',
+};
+
+async function main() {
+  console.log(`
+  ██████╗ ███████╗██╗   ██╗    ██╗     ██╗███╗   ██╗██╗   ██╗██╗  ██╗
+  ██╔══██╗██╔════╝██║   ██║    ██║     ██║████╗  ██║██║   ██║╚██╗██╔╝
+  ██║  ██║█████╗  ██║   ██║    ██║     ██║██╔██╗ ██║██║   ██║ ╚███╔╝ 
+  ██║  ██║██╔══╝  ╚██╗ ██╔╝    ██║     ██║██║╚██╗██║██║   ██║ ██╔██╗ 
+  ██████╔╝███████╗ ╚████╔╝     ███████╗██║██║ ╚████║╚██████╔╝██╔╝ ██╗
+  ╚═════╝ ╚══════╝  ╚═══╝      ╚══════╝╚═╝╚═╝  ╚═══╝ ╚═════╝ ╚═╝  ╚═╝
+  
+  OpenClaw Multi-Agent Communication Hub
+  `);
+
+  // Load config from environment or file
+  let config = DEFAULT_CONFIG;
+  const configPath = process.env.CONFIG_FILE;
+  if (configPath) {
+    try {
+      const fileConfig = JSON.parse(readFileSync(configPath, 'utf-8'));
+      config = { ...config, ...fileConfig };
+      console.log(`[WoClaw] Loaded config from ${configPath}`);
+    } catch (e) {
+      console.error(`[WoClaw] Failed to load config: ${e}`);
+      process.exit(1);
+    }
+  }
+
+  console.log(`[WoClaw] Configuration:`);
+  console.log(`  WebSocket Port: ${config.port}`);
+  console.log(`  REST Port: ${config.restPort}`);
+  console.log(`  Host: ${config.host}`);
+  console.log(`  Data Dir: ${config.dataDir}`);
+  console.log(`  Auth Token: ${config.authToken.substring(0, 8)}...`);
+  console.log('');
+
+  // Initialize database
+  const db = new ClawDB(config.dataDir);
+  console.log('[WoClaw] Database initialized');
+
+  // Initialize WebSocket server (this also creates TopicsManager and MemoryPool internally)
+  const wsServer = new WSServer(config, db);
+  
+  // Start REST API server with access to db, topics, memory
+  const restServer = new RestServer(config, db, wsServer.getTopicsManager(), wsServer.getMemoryPool());
+  restServer.start();
+  
+  console.log('[WoClaw] Server started successfully');
+  console.log('');
+  console.log('[WoClaw] Endpoints:');
+  console.log(`  WebSocket: ws://${config.host}:${config.port}`);
+  console.log(`  REST API:  http://${config.host}:${config.restPort}`);
+  console.log('');
+
+  // Graceful shutdown
+  const shutdown = () => {
+    console.log('[WoClaw] Shutting down...');
+    restServer.close();
+    wsServer.close();
+    process.exit(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+main().catch((e) => {
+  console.error('[WoClaw] Fatal error:', e);
+  process.exit(1);
+});

package/src/memory.ts

@@ -0,0 +1,48 @@
+import { ClawDB } from './db.js';
+import { DBMemory, OutboundMessage } from './types.js';
+
+export class MemoryPool {
+  private db: ClawDB;
+  private subscribers: Map<string, (msg: OutboundMessage) => void> = new Map();
+
+  constructor(db: ClawDB) {
+    this.db = db;
+  }
+
+  write(key: string, value: any, updatedBy: string): DBMemory {
+    const serialized = typeof value === 'string' ? value : JSON.stringify(value);
+    this.db.setMemory(key, serialized, updatedBy);
+    return this.db.getMemory(key)!;
+  }
+
+  read(key: string): DBMemory | undefined {
+    return this.db.getMemory(key);
+  }
+
+  delete(key: string): boolean {
+    return this.db.deleteMemory(key);
+  }
+
+  getAll(): DBMemory[] {
+    return this.db.getAllMemory();
+  }
+
+  // For agents that want to subscribe to memory changes
+  subscribe(agentId: string, callback: (msg: OutboundMessage) => void): void {
+    this.subscribers.set(agentId, callback);
+  }
+
+  unsubscribe(agentId: string): void {
+    this.subscribers.delete(agentId);
+  }
+
+  notifySubscribers(message: OutboundMessage): void {
+    for (const callback of this.subscribers.values()) {
+      try {
+        callback(message);
+      } catch (e) {
+        console.error('Error notifying subscriber:', e);
+      }
+    }
+  }
+}

package/src/rest_server.ts

@@ -0,0 +1,180 @@
+import http from 'http';
+import { ClawDB } from './db.js';
+import { TopicsManager } from './topics.js';
+import { MemoryPool } from './memory.js';
+import { Config } from './types.js';
+
+export class RestServer {
+  private server: http.Server | null = null;
+  private db: ClawDB;
+  private topics: TopicsManager;
+  private memory: MemoryPool;
+  private config: Config;
+
+  constructor(config: Config, db: ClawDB, topics: TopicsManager, memory: MemoryPool) {
+    this.config = config;
+    this.db = db;
+    this.topics = topics;
+    this.memory = memory;
+  }
+
+  start(): void {
+    this.server = http.createServer((req, res) => {
+      this.handleRequest(req, res);
+    });
+
+    this.server.listen(this.config.restPort, () => {
+      console.log(`[WoClaw] REST API running on http://${this.config.host}:${this.config.restPort}`);
+    });
+  }
+
+  private handleRequest(req: http.IncomingMessage, res: http.ServerResponse): void {
+    // CORS headers
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+
+    if (req.method === 'OPTIONS') {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+
+    const url = new URL(req.url || '/', `http://${req.headers.host}`);
+    const path = url.pathname;
+    const method = req.method || 'GET';
+
+    // Auth check for write operations
+    const authHeader = req.headers.authorization;
+    if (method !== 'GET' && authHeader !== `Bearer ${this.config.authToken}`) {
+      res.writeHead(401, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Unauthorized' }));
+      return;
+    }
+
+    try {
+      if (path === '/health') {
+        this.handleHealth(res);
+      } else if (path === '/topics') {
+        if (method === 'GET') {
+          this.handleTopicsList(res);
+        } else {
+          res.writeHead(405);
+          res.end(JSON.stringify({ error: 'Method not allowed' }));
+        }
+      } else if (path === '/memory') {
+        if (method === 'GET') {
+          this.handleMemoryList(res);
+        } else {
+          res.writeHead(405);
+          res.end(JSON.stringify({ error: 'Method not allowed' }));
+        }
+      } else if (path.startsWith('/memory/')) {
+        const key = decodeURIComponent(path.slice(8));
+        if (method === 'GET') {
+          this.handleMemoryGet(res, key);
+        } else if (method === 'DELETE') {
+          this.handleMemoryDelete(res, key);
+        } else {
+          res.writeHead(405);
+          res.end(JSON.stringify({ error: 'Method not allowed' }));
+        }
+      } else if (path.startsWith('/topics/')) {
+        const topicName = decodeURIComponent(path.slice(8));
+        if (method === 'GET') {
+          this.handleTopicMessages(res, topicName, url.searchParams.get('limit'));
+        } else {
+          res.writeHead(405);
+          res.end(JSON.stringify({ error: 'Method not allowed' }));
+        }
+      } else {
+        res.writeHead(404);
+        res.end(JSON.stringify({ error: 'Not found' }));
+      }
+    } catch (e: any) {
+      console.error('[WoClaw] REST error:', e.message);
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: e.message }));
+    }
+  }
+
+  private handleHealth(res: http.ServerResponse): void {
+    const stats = this.topics.getStats();
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      status: 'ok',
+      uptime: process.uptime(),
+      timestamp: Date.now(),
+      agents: stats.totalAgents,
+      topics: stats.totalTopics,
+    }));
+  }
+
+  private handleTopicsList(res: http.ServerResponse): void {
+    const stats = this.topics.getStats();
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      topics: stats.topicDetails.map(t => ({
+        name: t.name,
+        agents: t.agents,
+      }))
+    }));
+  }
+
+  private handleMemoryList(res: http.ServerResponse): void {
+    const allMemory = this.memory.getAll();
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      memory: allMemory.map(m => ({
+        key: m.key,
+        updatedAt: m.updatedAt,
+        updatedBy: m.updatedBy,
+      }))
+    }));
+  }
+
+  private handleMemoryGet(res: http.ServerResponse, key: string): void {
+    const mem = this.memory.read(key);
+    if (!mem) {
+      res.writeHead(404, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Key not found' }));
+      return;
+    }
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      key: mem.key,
+      value: mem.value,
+      updatedAt: mem.updatedAt,
+      updatedBy: mem.updatedBy,
+    }));
+  }
+
+  private handleMemoryDelete(res: http.ServerResponse, key: string): void {
+    const deleted = this.memory.delete(key);
+    if (!deleted) {
+      res.writeHead(404, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Key not found' }));
+      return;
+    }
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ success: true, key }));
+  }
+
+  private handleTopicMessages(res: http.ServerResponse, topic: string, limit?: string | null): void {
+    const limitNum = Math.min(parseInt(limit || '50'), 200);
+    const messages = this.db.getMessages(topic, limitNum);
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      topic,
+      messages: messages.reverse(),
+      count: messages.length,
+    }));
+  }
+
+  close(): void {
+    if (this.server) {
+      this.server.close();
+      console.log('[WoClaw] REST server closed');
+    }
+  }
+}