@the-open-engine/zeroshot 5.4.0

package/src/message-bus-bridge.js

@@ -0,0 +1,144 @@
+/**
+ * MessageBusBridge - Bridges parent and child message buses
+ *
+ * Forwards specified topics between parent and child clusters while maintaining
+ * isolation and preventing message loops.
+ *
+ * Features:
+ * - Forward specified parent topics to child (contextStrategy.parentTopics)
+ * - Forward child completion events to parent
+ * - Namespace child topics to avoid collisions
+ * - Prevent message loops via forwarding flags
+ */
+
+class MessageBusBridge {
+  constructor(parentBus, childBus, config) {
+    this.parentBus = parentBus;
+    this.childBus = childBus;
+    this.config = config;
+    this.parentTopicNames = new Set(
+      (config.parentTopics || [])
+        .map((entry) => (typeof entry === 'string' ? entry : entry?.topic))
+        .filter((topic) => typeof topic === 'string' && topic.length > 0)
+    );
+
+    this.parentUnsubscribe = null;
+    this.childUnsubscribe = null;
+    this.active = false;
+
+    this._setupBridge();
+  }
+
+  /**
+   * Set up bidirectional message forwarding
+   * @private
+   */
+  _setupBridge() {
+    // Forward specified parent topics to child
+    if (this.parentTopicNames.size > 0) {
+      this.parentUnsubscribe = this.parentBus.subscribe((message) => {
+        this._forwardParentToChild(message);
+      });
+    }
+
+    // Forward child completion/failure events to parent
+    this.childUnsubscribe = this.childBus.subscribe((message) => {
+      this._forwardChildToParent(message);
+    });
+
+    this.active = true;
+  }
+
+  /**
+   * Forward parent message to child cluster
+   * @private
+   */
+  _forwardParentToChild(message) {
+    // Only forward messages from parent cluster
+    if (message.cluster_id !== this.config.parentClusterId) {
+      return;
+    }
+
+    // Only forward topics specified in config
+    if (!this.parentTopicNames.has(message.topic)) {
+      return;
+    }
+
+    // Skip already-forwarded messages (prevent loops)
+    if (message.metadata?.forwarded) {
+      return;
+    }
+
+    // Forward to child with metadata flag
+    this.childBus.publish({
+      ...message,
+      cluster_id: this.config.childClusterId,
+      metadata: {
+        ...message.metadata,
+        forwarded: true,
+        forwardedFrom: this.config.parentClusterId,
+      },
+    });
+  }
+
+  /**
+   * Forward child message to parent cluster
+   * @private
+   */
+  _forwardChildToParent(message) {
+    // Only forward messages from child cluster
+    if (message.cluster_id !== this.config.childClusterId) {
+      return;
+    }
+
+    // Only forward completion/failure events
+    const forwardTopics = ['CLUSTER_COMPLETE', 'CLUSTER_FAILED', 'AGENT_ERROR'];
+    if (!forwardTopics.includes(message.topic)) {
+      return;
+    }
+
+    // Skip already-forwarded messages (prevent loops)
+    if (message.metadata?.forwarded) {
+      return;
+    }
+
+    // Forward to parent with namespaced topic and metadata flag
+    this.parentBus.publish({
+      ...message,
+      cluster_id: this.config.parentClusterId,
+      topic: `CHILD_${message.topic}`,
+      metadata: {
+        ...message.metadata,
+        forwarded: true,
+        forwardedFrom: this.config.childClusterId,
+        childClusterId: this.config.childClusterId,
+      },
+    });
+  }
+
+  /**
+   * Close the bridge and stop forwarding
+   */
+  close() {
+    if (this.parentUnsubscribe) {
+      this.parentUnsubscribe();
+      this.parentUnsubscribe = null;
+    }
+
+    if (this.childUnsubscribe) {
+      this.childUnsubscribe();
+      this.childUnsubscribe = null;
+    }
+
+    this.active = false;
+  }
+
+  /**
+   * Check if bridge is active
+   */
+  isActive() {
+    return this.active;
+  }
+}
+
+module.exports = MessageBusBridge;

package/src/message-bus.js

@@ -0,0 +1,256 @@
+/**
+ * MessageBus - Pub/sub layer over Ledger with WebSocket support
+ *
+ * Provides:
+ * - High-level publish/subscribe API
+ * - WebSocket broadcasting for UI clients
+ * - Topic-based routing
+ * - Real-time event distribution
+ */
+
+const EventEmitter = require('events');
+const Ledger = require('./ledger');
+
+// Expected listeners per cluster:
+// - 5 orchestrator subscriptions (CLUSTER_COMPLETE, CLUSTER_FAILED, AGENT_ERROR, AGENT_LIFECYCLE, CLUSTER_OPERATIONS)
+// - 1 ledger internal
+// - 1 per agent (can be 10+ with dynamic spawning)
+// - topic-specific listeners
+const MAX_LISTENERS = 50;
+
+class MessageBus extends EventEmitter {
+  constructor(ledger) {
+    super();
+    this.setMaxListeners(MAX_LISTENERS);
+    this.ledger = ledger || new Ledger();
+    this.wsClients = new Set();
+
+    // Forward ledger events
+    this.ledger.on('message', (message) => {
+      this.emit('message', message);
+      this._broadcastToWebSocket(message);
+    });
+  }
+
+  /**
+   * Publish a message to the ledger
+   * @param {Object} message - Message to publish
+   * @returns {Object} Published message with ID
+   */
+  publish(message) {
+    if (!message.cluster_id) {
+      throw new Error('cluster_id is required');
+    }
+
+    if (!message.topic) {
+      throw new Error('topic is required');
+    }
+
+    if (!message.sender) {
+      throw new Error('sender is required');
+    }
+
+    const published = this.ledger.append(message);
+
+    // If ledger is closed, append returns null - skip emission
+    if (!published) {
+      return null;
+    }
+
+    // Emit to topic-specific listeners
+    this.emit(`topic:${message.topic}`, published);
+
+    return published;
+  }
+
+  /**
+   * Subscribe to all messages
+   * @param {Function} callback - Called with each message
+   * @returns {Function} Unsubscribe function
+   */
+  subscribe(callback) {
+    this.on('message', callback);
+    return () => this.off('message', callback);
+  }
+
+  /**
+   * Subscribe to specific topic
+   * @param {String} topic - Topic to subscribe to
+   * @param {Function} callback - Called with matching messages
+   * @returns {Function} Unsubscribe function
+   */
+  subscribeTopic(topic, callback) {
+    const event = `topic:${topic}`;
+    this.on(event, callback);
+    return () => this.off(event, callback);
+  }
+
+  /**
+   * Subscribe to multiple topics
+   * @param {Array<String>} topics - Topics to subscribe to
+   * @param {Function} callback - Called with matching messages
+   * @returns {Function} Unsubscribe function
+   */
+  subscribeTopics(topics, callback) {
+    const unsubscribers = topics.map((topic) => this.subscribeTopic(topic, callback));
+    return () => unsubscribers.forEach((unsub) => unsub());
+  }
+
+  /**
+   * Query messages (passthrough to ledger)
+   */
+  query(criteria) {
+    return this.ledger.query(criteria);
+  }
+
+  /**
+   * Query guidance mailbox (passthrough to ledger)
+   */
+  queryGuidanceMailbox(criteria) {
+    return this.ledger.queryGuidanceMailbox(criteria);
+  }
+
+  /**
+   * Find last message (passthrough to ledger)
+   */
+  findLast(criteria) {
+    return this.ledger.findLast(criteria);
+  }
+
+  /**
+   * Count messages (passthrough to ledger)
+   */
+  count(criteria) {
+    return this.ledger.count(criteria);
+  }
+
+  /**
+   * Get messages since timestamp (passthrough to ledger)
+   */
+  since(params) {
+    return this.ledger.since(params);
+  }
+
+  /**
+   * Get all messages (passthrough to ledger)
+   */
+  getAll(cluster_id) {
+    return this.ledger.getAll(cluster_id);
+  }
+
+  /**
+   * Publish multiple messages atomically
+   * All messages are committed in a single transaction with contiguous timestamps.
+   * Use this for task completion to prevent message interleaving between agents.
+   *
+   * @param {Array<Object>} messages - Array of messages to publish
+   * @returns {Array<Object>} Published messages with IDs
+   */
+  batchPublish(messages) {
+    // Validate all messages
+    for (const message of messages) {
+      if (!message.cluster_id) {
+        throw new Error('cluster_id is required for all messages');
+      }
+      if (!message.topic) {
+        throw new Error('topic is required for all messages');
+      }
+      if (!message.sender) {
+        throw new Error('sender is required for all messages');
+      }
+    }
+
+    // Delegate to ledger's atomic batchAppend
+    const published = this.ledger.batchAppend(messages);
+
+    // Emit to topic-specific listeners for each message
+    for (const msg of published) {
+      this.emit(`topic:${msg.topic}`, msg);
+    }
+
+    return published;
+  }
+
+  /**
+   * Get aggregated token usage by role (passthrough to ledger)
+   * @param {String} cluster_id - Cluster ID
+   * @returns {Object} Token usage aggregated by role with _total key
+   */
+  getTokensByRole(cluster_id) {
+    return this.ledger.getTokensByRole(cluster_id);
+  }
+
+  /**
+   * Register a WebSocket client for broadcasts
+   * @param {WebSocket} ws - WebSocket connection
+   */
+  addWebSocketClient(ws) {
+    this.wsClients.add(ws);
+
+    ws.on('close', () => {
+      this.wsClients.delete(ws);
+    });
+
+    ws.on('error', () => {
+      this.wsClients.delete(ws);
+    });
+  }
+
+  /**
+   * Remove a WebSocket client
+   * @param {WebSocket} ws - WebSocket connection
+   */
+  removeWebSocketClient(ws) {
+    this.wsClients.delete(ws);
+  }
+
+  /**
+   * Broadcast message to all WebSocket clients
+   * @private
+   */
+  _broadcastToWebSocket(message) {
+    const payload = JSON.stringify({
+      type: 'message',
+      data: message,
+    });
+
+    for (const ws of this.wsClients) {
+      if (ws.readyState === 1) {
+        // OPEN
+        try {
+          ws.send(payload);
+        } catch (error) {
+          console.error('WebSocket send error:', error);
+          this.wsClients.delete(ws);
+        }
+      }
+    }
+  }
+
+  /**
+   * Close the message bus
+   */
+  close() {
+    // Close all WebSocket connections
+    for (const ws of this.wsClients) {
+      try {
+        ws.close();
+      } catch {
+        // Ignore errors on close
+      }
+    }
+    this.wsClients.clear();
+
+    // Close ledger
+    this.ledger.close();
+  }
+
+  /**
+   * Clear all messages (for testing)
+   */
+  clear() {
+    this.ledger.clear();
+  }
+}
+
+module.exports = MessageBus;

package/src/name-generator.js

@@ -0,0 +1,232 @@
+/**
+ * Human-readable name generator (like Weights & Biases)
+ * Generates names like "wandering-forest-42" or "bright-star-17"
+ *
+ * No prefix - short forms used everywhere for simplicity
+ */
+
+const ADJECTIVES = [
+  // Colors
+  'amber',
+  'azure',
+  'crimson',
+  'emerald',
+  'golden',
+  'indigo',
+  'jade',
+  'ruby',
+  'sapphire',
+  'silver',
+  'violet',
+  'bronze',
+  'coral',
+  'ivory',
+  'pearl',
+  'platinum',
+  'scarlet',
+  'cobalt',
+  'copper',
+  'obsidian',
+  'onyx',
+  'opal',
+  'topaz',
+  'turquoise',
+  // Nature
+  'wandering',
+  'bright',
+  'silent',
+  'ancient',
+  'swift',
+  'noble',
+  'bold',
+  'wild',
+  'gentle',
+  'hidden',
+  'fierce',
+  'calm',
+  'frozen',
+  'misty',
+  'stormy',
+  'sunny',
+  // Cosmic
+  'cosmic',
+  'crystal',
+  'electric',
+  'lunar',
+  'solar',
+  'stellar',
+  'astral',
+  'orbital',
+  'mystic',
+  'quantum',
+  'radiant',
+  'twilight',
+  'vivid',
+  'zen',
+  'infinite',
+  'eternal',
+  // Tech/Abstract
+  'clever',
+  'rapid',
+  'steady',
+  'agile',
+  'nimble',
+  'keen',
+  'sharp',
+  'quick',
+  'prime',
+  'binary',
+  'neural',
+  'atomic',
+  'sonic',
+  'hyper',
+  'mega',
+  'ultra',
+  // Descriptive
+  'blazing',
+  'gleaming',
+  'glowing',
+  'shining',
+  'burning',
+  'flaming',
+  'sparkling',
+  'dazzling',
+  'roaring',
+  'rushing',
+  'soaring',
+  'flying',
+  'rising',
+  'falling',
+  'spinning',
+  'dancing',
+];
+
+const NOUNS = [
+  // Nature
+  'forest',
+  'river',
+  'mountain',
+  'ocean',
+  'thunder',
+  'canyon',
+  'summit',
+  'valley',
+  'cascade',
+  'glacier',
+  'volcano',
+  'desert',
+  'meadow',
+  'tundra',
+  'jungle',
+  'reef',
+  // Space
+  'star',
+  'comet',
+  'nebula',
+  'galaxy',
+  'pulsar',
+  'quasar',
+  'aurora',
+  'eclipse',
+  'meteor',
+  'nova',
+  'cosmos',
+  'orbit',
+  'void',
+  'horizon',
+  'zenith',
+  'equinox',
+  // Mythical
+  'phoenix',
+  'dragon',
+  'griffin',
+  'sphinx',
+  'hydra',
+  'kraken',
+  'titan',
+  'atlas',
+  'oracle',
+  'rune',
+  'sigil',
+  'glyph',
+  'totem',
+  'aegis',
+  'aether',
+  'flux',
+  // Animals
+  'falcon',
+  'eagle',
+  'wolf',
+  'bear',
+  'tiger',
+  'hawk',
+  'lion',
+  'panther',
+  'raven',
+  'serpent',
+  'shark',
+  'owl',
+  'fox',
+  'lynx',
+  'viper',
+  'condor',
+  // Architecture
+  'citadel',
+  'temple',
+  'spire',
+  'tower',
+  'fortress',
+  'bastion',
+  'vault',
+  'sanctum',
+  'beacon',
+  'arch',
+  'bridge',
+  'gate',
+  'hall',
+  'keep',
+  'dome',
+  'obelisk',
+  // Abstract
+  'cipher',
+  'echo',
+  'nexus',
+  'prism',
+  'relic',
+  'vertex',
+  'vortex',
+  'pulse',
+  'surge',
+  'spark',
+  'flame',
+  'storm',
+  'wave',
+  'drift',
+  'shift',
+  'core',
+];
+
+// 96 adjectives × 96 nouns × 100 numbers = 921,600 combinations
+
+/**
+ * Generate a human-readable name
+ * @param {string} _prefix - DEPRECATED: Ignored for backwards compat, short form always used
+ * @returns {string} Human-readable name (e.g., 'wandering-forest-42')
+ */
+function generateName(_prefix = '') {
+  const adjective = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)];
+  const noun = NOUNS[Math.floor(Math.random() * NOUNS.length)];
+  const number = Math.floor(Math.random() * 100);
+
+  return `${adjective}-${noun}-${number}`;
+}
+
+/**
+ * Generate a short unique suffix (for collision prevention)
+ * @returns {string} Short random suffix (e.g., 'a3f9')
+ */
+function generateSuffix() {
+  return Math.random().toString(36).slice(2, 6);
+}
+
+module.exports = { generateName, generateSuffix };