@covibes/zeroshot 1.0.1

package/src/schemas/sub-cluster.js

@@ -0,0 +1,156 @@
+/**
+ * Sub-Cluster Schema
+ *
+ * Defines the structure for nested clusters where an agent can be replaced
+ * with an entire cluster configuration, enabling recursive composition.
+ *
+ * Example:
+ * {
+ *   "id": "implementation-cluster",
+ *   "type": "subcluster",
+ *   "config": {
+ *     "agents": [
+ *       { "id": "worker", "role": "implementation", ... },
+ *       { "id": "validator", "role": "validator", ... }
+ *     ]
+ *   },
+ *   "triggers": [{ "topic": "PLAN_READY" }],
+ *   "hooks": {
+ *     "onComplete": {
+ *       "action": "publish_message",
+ *       "config": { "topic": "IMPLEMENTATION_COMPLETE" }
+ *     }
+ *   }
+ * }
+ */
+
+/**
+ * Validate sub-cluster agent configuration
+ * @param {Object} agentConfig - Agent config with type: 'subcluster'
+ * @param {Number} depth - Current nesting depth (for recursion limit)
+ * @returns {{ valid: boolean, errors: string[], warnings: string[] }}
+ */
+function validateSubCluster(agentConfig, depth = 0) {
+  const errors = [];
+  const warnings = [];
+
+  // Max nesting depth to prevent infinite recursion
+  const MAX_DEPTH = 5;
+
+  if (depth > MAX_DEPTH) {
+    errors.push(`Sub-cluster '${agentConfig.id}' exceeds max nesting depth (${MAX_DEPTH})`);
+    return { valid: false, errors, warnings };
+  }
+
+  // Validate required fields
+  if (agentConfig.type !== 'subcluster') {
+    errors.push(`Agent '${agentConfig.id}' must have type: 'subcluster'`);
+  }
+
+  if (!agentConfig.config) {
+    errors.push(`Sub-cluster '${agentConfig.id}' missing config field`);
+    return { valid: false, errors, warnings };
+  }
+
+  if (!agentConfig.config.agents || !Array.isArray(agentConfig.config.agents)) {
+    errors.push(`Sub-cluster '${agentConfig.id}' config.agents must be an array`);
+    return { valid: false, errors, warnings };
+  }
+
+  if (agentConfig.config.agents.length === 0) {
+    errors.push(`Sub-cluster '${agentConfig.id}' config.agents cannot be empty`);
+    return { valid: false, errors, warnings };
+  }
+
+  // Recursively validate nested cluster config
+  const configValidator = require('../config-validator');
+  const childValidation = configValidator.validateConfig(agentConfig.config, depth + 1);
+
+  if (!childValidation.valid) {
+    errors.push(...childValidation.errors.map((e) => `Sub-cluster '${agentConfig.id}': ${e}`));
+  }
+
+  warnings.push(...childValidation.warnings.map((w) => `Sub-cluster '${agentConfig.id}': ${w}`));
+
+  // Validate triggers (sub-cluster must have triggers to activate)
+  if (!agentConfig.triggers || agentConfig.triggers.length === 0) {
+    errors.push(`Sub-cluster '${agentConfig.id}' must have triggers to activate`);
+  }
+
+  // Validate hooks structure
+  if (agentConfig.hooks) {
+    if (agentConfig.hooks.onComplete) {
+      const hook = agentConfig.hooks.onComplete;
+      if (!hook.action) {
+        errors.push(`Sub-cluster '${agentConfig.id}' onComplete hook missing action`);
+      }
+      if (hook.action === 'publish_message' && !hook.config?.topic) {
+        errors.push(`Sub-cluster '${agentConfig.id}' onComplete hook missing config.topic`);
+      }
+    }
+  }
+
+  // Check for context bridging configuration
+  if (agentConfig.contextStrategy?.parentTopics) {
+    if (!Array.isArray(agentConfig.contextStrategy.parentTopics)) {
+      errors.push(`Sub-cluster '${agentConfig.id}' contextStrategy.parentTopics must be an array`);
+    } else {
+      // Validate each parent topic is a string
+      for (const topic of agentConfig.contextStrategy.parentTopics) {
+        if (typeof topic !== 'string') {
+          errors.push(
+            `Sub-cluster '${agentConfig.id}' parentTopics must contain strings, got ${typeof topic}`
+          );
+        }
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Get default sub-cluster template
+ * @returns {Object} Default sub-cluster configuration
+ */
+function getDefaultSubCluster() {
+  return {
+    id: 'example-subcluster',
+    type: 'subcluster',
+    role: 'orchestrator',
+    config: {
+      agents: [
+        {
+          id: 'worker',
+          role: 'implementation',
+          triggers: [{ topic: 'PARENT_TRIGGER' }],
+          hooks: {
+            onComplete: {
+              action: 'publish_message',
+              config: { topic: 'WORK_COMPLETE' },
+            },
+          },
+        },
+      ],
+    },
+    triggers: [{ topic: 'START_WORK' }],
+    hooks: {
+      onComplete: {
+        action: 'publish_message',
+        config: { topic: 'SUBCLUSTER_COMPLETE' },
+      },
+    },
+    contextStrategy: {
+      parentTopics: ['ISSUE_OPENED', 'PLAN_READY'],
+    },
+  };
+}
+
+module.exports = {
+  validateSubCluster,
+  getDefaultSubCluster,
+};

package/src/sub-cluster-wrapper.js

@@ -0,0 +1,545 @@
+/**
+ * SubClusterWrapper - Manages nested cluster lifecycle
+ *
+ * Implements same interface as AgentWrapper but spawns a child Orchestrator
+ * instead of a Claude task. Enables recursive cluster composition.
+ *
+ * Lifecycle:
+ * - On trigger match: spawns nested Orchestrator with child cluster config
+ * - Passes parent context to child via ISSUE_OPENED equivalent
+ * - Listens for child CLUSTER_COMPLETE → executes onComplete hook
+ * - Listens for child CLUSTER_FAILED → executes onError hook
+ * - Supports maxIterations at subcluster level (restart child on failure)
+ */
+
+const LogicEngine = require('./logic-engine');
+const MessageBusBridge = require('./message-bus-bridge');
+const { DEFAULT_MAX_ITERATIONS } = require('./agent/agent-config');
+
+class SubClusterWrapper {
+  constructor(config, messageBus, parentCluster, options = {}) {
+    this.id = config.id;
+    this.role = config.role || 'orchestrator';
+    this.config = config;
+    this.messageBus = messageBus; // Parent message bus
+    this.parentCluster = parentCluster;
+    this.logicEngine = new LogicEngine(messageBus, parentCluster);
+
+    this.state = 'idle';
+    this.iteration = 0;
+    this.maxIterations = config.maxIterations || DEFAULT_MAX_ITERATIONS;
+    this.running = false;
+    this.unsubscribe = null;
+
+    // Child cluster state
+    this.childCluster = null; // { id, orchestrator, messageBus, bridge }
+    this.childClusterId = null;
+
+    this.quiet = options.quiet || false;
+  }
+
+  /**
+   * Log message (respects quiet mode)
+   * @private
+   */
+  _log(...args) {
+    if (!this.quiet) {
+      console.log(...args);
+    }
+  }
+
+  /**
+   * Publish lifecycle event to parent message bus
+   * @private
+   */
+  _publishLifecycle(event, details = {}) {
+    this.messageBus.publish({
+      cluster_id: this.parentCluster.id,
+      topic: 'AGENT_LIFECYCLE',
+      sender: this.id,
+      receiver: 'system',
+      content: {
+        text: `${this.id}: ${event}`,
+        data: {
+          event,
+          agent: this.id,
+          role: this.role,
+          state: this.state,
+          type: 'subcluster',
+          ...details,
+        },
+      },
+    });
+  }
+
+  /**
+   * Start the sub-cluster wrapper (begin listening for triggers)
+   */
+  start() {
+    if (this.running) {
+      throw new Error(`SubCluster ${this.id} is already running`);
+    }
+
+    this.running = true;
+    this.state = 'idle';
+
+    // Subscribe to parent cluster messages
+    this.unsubscribe = this.messageBus.subscribe((message) => {
+      if (message.cluster_id === this.parentCluster.id) {
+        this._handleMessage(message).catch((error) => {
+          console.error(`\n${'='.repeat(80)}`);
+          console.error(`🔴 FATAL: SubCluster ${this.id} message handler crashed`);
+          console.error(`${'='.repeat(80)}`);
+          console.error(`Topic: ${message.topic}`);
+          console.error(`Error: ${error.message}`);
+          console.error(`Stack: ${error.stack}`);
+          console.error(`${'='.repeat(80)}\n`);
+          throw error;
+        });
+      }
+    });
+
+    this._log(`SubCluster ${this.id} started (role: ${this.role})`);
+    this._publishLifecycle('STARTED', {
+      triggers: this.config.triggers?.map((t) => t.topic) || [],
+    });
+  }
+
+  /**
+   * Stop the sub-cluster wrapper
+   */
+  async stop() {
+    if (!this.running) {
+      return;
+    }
+
+    this.running = false;
+    this.state = 'stopped';
+
+    if (this.unsubscribe) {
+      this.unsubscribe();
+      this.unsubscribe = null;
+    }
+
+    // Stop child cluster if running
+    if (this.childCluster) {
+      await this._stopChildCluster();
+    }
+
+    this._log(`SubCluster ${this.id} stopped`);
+  }
+
+  /**
+   * Handle incoming message from parent cluster
+   * @private
+   */
+  async _handleMessage(message) {
+    // Check if any trigger matches
+    const matchingTrigger = this._findMatchingTrigger(message);
+    if (!matchingTrigger) {
+      return;
+    }
+
+    // Check state
+    if (!this.running) {
+      console.warn(`[${this.id}] ⚠️ DROPPING message (not running): ${message.topic}`);
+      return;
+    }
+    if (this.state !== 'idle') {
+      console.warn(
+        `[${this.id}] ⚠️ DROPPING message (busy, state=${this.state}): ${message.topic}`
+      );
+      return;
+    }
+
+    // Evaluate trigger logic
+    this.state = 'evaluating_logic';
+    const shouldExecute = this._evaluateTrigger(matchingTrigger, message);
+
+    if (!shouldExecute) {
+      this.state = 'idle';
+      return;
+    }
+
+    // Execute trigger action (spawn child cluster)
+    await this._handleTrigger(message);
+  }
+
+  /**
+   * Find trigger matching the message topic
+   * @private
+   */
+  _findMatchingTrigger(message) {
+    if (!this.config.triggers) {
+      return null;
+    }
+
+    return this.config.triggers.find((trigger) => {
+      if (trigger.topic === '*' || trigger.topic === message.topic) {
+        return true;
+      }
+      if (trigger.topic.endsWith('*')) {
+        const prefix = trigger.topic.slice(0, -1);
+        return message.topic.startsWith(prefix);
+      }
+      return false;
+    });
+  }
+
+  /**
+   * Evaluate trigger logic
+   * @private
+   */
+  _evaluateTrigger(trigger, message) {
+    if (!trigger.logic || !trigger.logic.script) {
+      return true;
+    }
+
+    const agent = {
+      id: this.id,
+      role: this.role,
+      iteration: this.iteration,
+      cluster_id: this.parentCluster.id,
+    };
+
+    return this.logicEngine.evaluate(trigger.logic.script, agent, message);
+  }
+
+  /**
+   * Handle trigger: spawn child cluster
+   * @private
+   */
+  async _handleTrigger(triggeringMessage) {
+    // Check max iterations
+    if (this.iteration >= this.maxIterations) {
+      this._log(`[SubCluster ${this.id}] Hit max iterations (${this.maxIterations}), failing`);
+      this._publishLifecycle('MAX_ITERATIONS_REACHED', {
+        iteration: this.iteration,
+        maxIterations: this.maxIterations,
+      });
+
+      this.messageBus.publish({
+        cluster_id: this.parentCluster.id,
+        topic: 'CLUSTER_FAILED',
+        sender: this.id,
+        receiver: 'system',
+        content: {
+          text: `SubCluster ${this.id} hit max iterations limit (${this.maxIterations})`,
+          data: {
+            reason: 'max_iterations',
+            iteration: this.iteration,
+            maxIterations: this.maxIterations,
+          },
+        },
+      });
+
+      this.state = 'failed';
+      return;
+    }
+
+    this.iteration++;
+    this.state = 'spawning_child';
+
+    this._publishLifecycle('SPAWNING_CHILD', {
+      iteration: this.iteration,
+      triggeredBy: triggeringMessage.topic,
+    });
+
+    try {
+      // Build child cluster context from parent messages
+      const context = this._buildChildContext(triggeringMessage);
+
+      // Spawn child cluster
+      await this._spawnChildCluster(context);
+
+      this._publishLifecycle('CHILD_SPAWNED', {
+        childClusterId: this.childClusterId,
+        iteration: this.iteration,
+      });
+
+      this.state = 'monitoring_child';
+    } catch (error) {
+      console.error(`\n${'='.repeat(80)}`);
+      console.error(`🔴 CHILD CLUSTER SPAWN FAILED - ${this.id}`);
+      console.error(`${'='.repeat(80)}`);
+      console.error(`Error: ${error.message}`);
+      console.error(`Stack: ${error.stack}`);
+      console.error(`${'='.repeat(80)}\n`);
+
+      this.state = 'error';
+
+      // Execute onError hook
+      await this._executeHook('onError', { error, triggeringMessage });
+
+      // Return to idle if we haven't hit max iterations
+      if (this.iteration < this.maxIterations) {
+        this.state = 'idle';
+      }
+    }
+  }
+
+  /**
+   * Build context for child cluster from parent messages
+   * @private
+   */
+  _buildChildContext(triggeringMessage) {
+    const parentTopics = this.config.contextStrategy?.parentTopics || [];
+
+    let context = `# Child Cluster Context\n\n`;
+    context += `Parent Cluster: ${this.parentCluster.id}\n`;
+    context += `SubCluster ID: ${this.id}\n`;
+    context += `Iteration: ${this.iteration}\n\n`;
+
+    // Add messages from specified parent topics
+    if (parentTopics.length > 0) {
+      context += `## Parent Cluster Messages\n\n`;
+
+      for (const topic of parentTopics) {
+        const messages = this.messageBus.query({
+          cluster_id: this.parentCluster.id,
+          topic,
+          limit: 10,
+        });
+
+        if (messages.length > 0) {
+          context += `### Topic: ${topic}\n\n`;
+          for (const msg of messages) {
+            context += `[${new Date(msg.timestamp).toISOString()}] ${msg.sender}:\n`;
+            if (msg.content?.text) {
+              context += `${msg.content.text}\n`;
+            }
+            if (msg.content?.data) {
+              context += `Data: ${JSON.stringify(msg.content.data, null, 2)}\n`;
+            }
+            context += '\n';
+          }
+        }
+      }
+    }
+
+    // Add triggering message
+    context += `\n## Triggering Message\n\n`;
+    context += `Topic: ${triggeringMessage.topic}\n`;
+    context += `Sender: ${triggeringMessage.sender}\n`;
+    if (triggeringMessage.content?.text) {
+      context += `\n${triggeringMessage.content.text}\n`;
+    }
+
+    return context;
+  }
+
+  /**
+   * Spawn child cluster with nested Orchestrator
+   * @private
+   */
+  async _spawnChildCluster(context) {
+    const Orchestrator = require('./orchestrator');
+    const path = require('path');
+
+    // Generate child cluster ID (namespaced under parent)
+    const childId = `${this.parentCluster.id}.${this.id}`;
+    this.childClusterId = childId;
+
+    // Create child orchestrator with separate database
+    const childOrchestrator = new Orchestrator({
+      quiet: this.quiet,
+      skipLoad: true,
+      storageDir: path.join(this.parentCluster.ledger.dbPath, '..', 'subclusters', childId),
+    });
+
+    // Start child cluster with text input (context from parent)
+    const childCluster = await childOrchestrator.start(
+      this.config.config, // Child cluster config
+      { text: context },
+      { testMode: false }
+    );
+
+    // Create message bridge
+    const bridge = new MessageBusBridge(this.messageBus, childCluster.messageBus, {
+      parentClusterId: this.parentCluster.id,
+      childClusterId: childId,
+      parentTopics: this.config.contextStrategy?.parentTopics || [],
+    });
+
+    // Store child cluster state
+    this.childCluster = {
+      id: childId,
+      orchestrator: childOrchestrator,
+      messageBus: childCluster.messageBus,
+      bridge,
+    };
+
+    // Listen for child cluster completion
+    childCluster.messageBus.subscribe((message) => {
+      if (message.topic === 'CLUSTER_COMPLETE' && message.cluster_id === childId) {
+        this._onChildComplete(message).catch((err) => {
+          console.error(`Failed to handle child completion: ${err.message}`);
+        });
+      }
+    });
+
+    // Listen for child cluster failure
+    childCluster.messageBus.subscribe((message) => {
+      if (message.topic === 'CLUSTER_FAILED' && message.cluster_id === childId) {
+        this._onChildFailed(message).catch((err) => {
+          console.error(`Failed to handle child failure: ${err.message}`);
+        });
+      }
+    });
+  }
+
+  /**
+   * Handle child cluster completion
+   * @private
+   */
+  async _onChildComplete(message) {
+    this._log(`[SubCluster ${this.id}] Child cluster completed`);
+
+    this._publishLifecycle('CHILD_COMPLETE', {
+      childClusterId: this.childClusterId,
+      iteration: this.iteration,
+    });
+
+    // Execute onComplete hook
+    await this._executeHook('onComplete', {
+      result: message,
+      triggeringMessage: null,
+    });
+
+    // Clean up child cluster
+    await this._stopChildCluster();
+
+    this.state = 'idle';
+  }
+
+  /**
+   * Handle child cluster failure
+   * @private
+   */
+  async _onChildFailed(message) {
+    this._log(`[SubCluster ${this.id}] Child cluster failed`);
+
+    this._publishLifecycle('CHILD_FAILED', {
+      childClusterId: this.childClusterId,
+      iteration: this.iteration,
+      error: message.content?.data?.reason,
+    });
+
+    // Execute onError hook
+    const error = new Error(message.content?.data?.reason || 'Child cluster failed');
+    await this._executeHook('onError', { error, triggeringMessage: null });
+
+    // Clean up child cluster
+    await this._stopChildCluster();
+
+    // Retry if within max iterations
+    if (this.iteration < this.maxIterations) {
+      this.state = 'idle';
+    } else {
+      this.state = 'failed';
+    }
+  }
+
+  /**
+   * Stop child cluster
+   * @private
+   */
+  async _stopChildCluster() {
+    if (!this.childCluster) {
+      return;
+    }
+
+    // Close message bridge
+    if (this.childCluster.bridge) {
+      this.childCluster.bridge.close();
+    }
+
+    // Stop child orchestrator
+    try {
+      await this.childCluster.orchestrator.stop(this.childCluster.id);
+    } catch (err) {
+      console.warn(`Warning: Failed to stop child cluster ${this.childCluster.id}: ${err.message}`);
+    }
+
+    this.childCluster = null;
+    this.childClusterId = null;
+  }
+
+  /**
+   * Execute a hook
+   * @private
+   */
+  _executeHook(hookName, context) {
+    const hook = this.config.hooks?.[hookName];
+    if (!hook) {
+      return;
+    }
+
+    if (hook.action === 'publish_message') {
+      const message = this._substituteTemplate(hook.config, context);
+      this.messageBus.publish({
+        cluster_id: this.parentCluster.id,
+        sender: this.id,
+        ...message,
+      });
+    } else {
+      throw new Error(`Unknown hook action: ${hook.action}`);
+    }
+  }
+
+  /**
+   * Substitute template variables in hook config
+   * @private
+   */
+  _substituteTemplate(config, context) {
+    if (!config) {
+      throw new Error('_substituteTemplate: config is required');
+    }
+
+    const json = JSON.stringify(config);
+
+    let substituted = json
+      .replace(/\{\{cluster\.id\}\}/g, this.parentCluster.id)
+      .replace(/\{\{subcluster\.id\}\}/g, this.id)
+      .replace(/\{\{child\.id\}\}/g, this.childClusterId || '')
+      .replace(/\{\{iteration\}\}/g, String(this.iteration))
+      .replace(/\{\{error\.message\}\}/g, context.error?.message || '');
+
+    // Parse and validate
+    let result;
+    try {
+      result = JSON.parse(substituted);
+    } catch (e) {
+      console.error('JSON parse failed. Substituted string:');
+      console.error(substituted);
+      throw new Error(`Template substitution produced invalid JSON: ${e.message}`);
+    }
+
+    return result;
+  }
+
+  /**
+   * Resume sub-cluster task (not implemented for subclusters)
+   */
+  resume(_resumeContext) {
+    throw new Error('Resume not implemented for subclusters');
+  }
+
+  /**
+   * Get current sub-cluster state
+   */
+  getState() {
+    return {
+      id: this.id,
+      role: this.role,
+      state: this.state,
+      iteration: this.iteration,
+      maxIterations: this.maxIterations,
+      type: 'subcluster',
+      childClusterId: this.childClusterId,
+      childRunning: this.childCluster !== null,
+    };
+  }
+}
+
+module.exports = SubClusterWrapper;