@covibes/zeroshot 1.0.1

package/src/agent/agent-trigger-evaluator.js

@@ -0,0 +1,67 @@
+/**
+ * AgentTriggerEvaluator - Trigger matching and logic evaluation
+ *
+ * Provides:
+ * - Trigger matching based on message topics
+ * - Logic evaluation via LogicEngine
+ * - Trigger action determination
+ */
+
+/**
+ * Find trigger matching the message topic
+ * @param {Object} params - Evaluation parameters
+ * @param {Array} params.triggers - Agent triggers configuration
+ * @param {Object} params.message - Message to match against
+ * @returns {Object|null} Matching trigger or null
+ */
+function findMatchingTrigger({ triggers, message }) {
+  if (!triggers) {
+    return null;
+  }
+
+  return triggers.find((trigger) => {
+    // Match exact topic or wildcard
+    if (trigger.topic === '*' || trigger.topic === message.topic) {
+      return true;
+    }
+    // Match topic prefix (e.g., "VALIDATION_*")
+    if (trigger.topic.endsWith('*')) {
+      const prefix = trigger.topic.slice(0, -1);
+      return message.topic.startsWith(prefix);
+    }
+    return false;
+  });
+}
+
+/**
+ * Evaluate trigger logic
+ * @param {Object} params - Evaluation parameters
+ * @param {Object} params.trigger - Trigger to evaluate
+ * @param {Object} params.message - Triggering message
+ * @param {Object} params.agent - Agent context (id, role, iteration, cluster_id)
+ * @param {Object} params.logicEngine - LogicEngine instance
+ * @returns {boolean} Whether trigger logic passed
+ */
+function evaluateTrigger({ trigger, message, agent, logicEngine }) {
+  if (!trigger.logic || !trigger.logic.script) {
+    return true; // No logic = always true
+  }
+
+  // NO TRY/CATCH - let errors propagate and crash
+  return logicEngine.evaluate(trigger.logic.script, agent, message);
+}
+
+/**
+ * Get trigger action type
+ * @param {Object} trigger - Trigger object
+ * @returns {string} Action type ('execute_task' or 'stop_cluster')
+ */
+function getTriggerAction(trigger) {
+  return trigger.action || 'execute_task';
+}
+
+module.exports = {
+  findMatchingTrigger,
+  evaluateTrigger,
+  getTriggerAction,
+};

package/src/agent-wrapper.js

@@ -0,0 +1,459 @@
+// @ts-nocheck
+/**
+ * AgentWrapper - Manages agent lifecycle and claude-zeroshots execution
+ *
+ * Provides:
+ * - Agent state machine (idle -> evaluating -> building context -> executing -> idle)
+ * - Trigger evaluation via LogicEngine
+ * - Context building from ledger
+ * - claude-zeroshots spawning and monitoring
+ * - Hook execution (onStart, onComplete, onError)
+ */
+
+const LogicEngine = require('./logic-engine');
+const { validateAgentConfig } = require('./agent/agent-config');
+const { buildContext } = require('./agent/agent-context-builder');
+const { findMatchingTrigger, evaluateTrigger } = require('./agent/agent-trigger-evaluator');
+const { executeHook } = require('./agent/agent-hook-executor');
+const {
+  spawnClaudeTask,
+  followClaudeTaskLogs,
+  waitForTaskReady,
+  spawnClaudeTaskIsolated,
+  getClaudeTasksPath,
+  parseResultOutput,
+  killTask,
+} = require('./agent/agent-task-executor');
+const {
+  start: lifecycleStart,
+  stop: lifecycleStop,
+  handleMessage: lifecycleHandleMessage,
+  executeTriggerAction: lifecycleExecuteTriggerAction,
+  executeTask: lifecycleExecuteTask,
+  startLivenessCheck: lifecycleStartLivenessCheck,
+  stopLivenessCheck: lifecycleStopLivenessCheck,
+} = require('./agent/agent-lifecycle');
+
+class AgentWrapper {
+  /**
+   * @param {any} config - Agent configuration
+   * @param {any} messageBus - Message bus instance
+   * @param {any} cluster - Cluster instance
+   * @param {any} options - Options
+   */
+  constructor(config, messageBus, cluster, options = {}) {
+    // Validate and normalize configuration
+    const normalizedConfig = validateAgentConfig(config, options);
+
+    this.id = normalizedConfig.id;
+    this.role = normalizedConfig.role;
+    this.modelConfig = normalizedConfig.modelConfig;
+    this.config = normalizedConfig;
+    this.messageBus = messageBus;
+    this.cluster = cluster;
+    this.logicEngine = new LogicEngine(messageBus, cluster);
+
+    this.state = 'idle';
+    this.iteration = 0;
+    this.maxIterations = normalizedConfig.maxIterations;
+    this.timeout = normalizedConfig.timeout;
+    /** @type {any} */
+    this.currentTask = null;
+    /** @type {string | null} */
+    this.currentTaskId = null; // Track spawned task ID for resume capability
+    /** @type {number | null} */
+    this.processPid = null; // Track process PID for resource monitoring
+    this.running = false;
+    /** @type {Function | null} */
+    this.unsubscribe = null;
+    /** @type {number | null} */
+    this.lastTaskEndTime = null; // Track when last task completed (for context filtering)
+
+    // LIVENESS DETECTION - Track output freshness to detect stuck agents
+    /** @type {number | null} */
+    this.lastOutputTime = null; // Timestamp of last output received
+    /** @type {NodeJS.Timeout | null} */
+    this.livenessCheckInterval = null; // Interval for health checks
+    this.staleDuration = normalizedConfig.staleDuration;
+    this.enableLivenessCheck = normalizedConfig.enableLivenessCheck;
+
+    // MOCK SUPPORT - Inject mock spawn function for testing
+    // When set, _spawnClaudeTask uses this instead of real ct CLI
+    this.mockSpawnFn = options.mockSpawnFn || null;
+    this.testMode = options.testMode || false;
+    this.quiet = options.quiet || false;
+
+    // ISOLATION SUPPORT - Run tasks inside Docker container
+    this.isolation = options.isolation || null;
+  }
+
+  /**
+   * Log message (respects quiet mode)
+   * @private
+   */
+  _log(...args) {
+    if (!this.quiet) {
+      console.log(...args);
+    }
+  }
+
+  /**
+   * Publish a message to the message bus, always including sender_model
+   * @private
+   */
+  _publish(message) {
+    this.messageBus.publish({
+      ...message,
+      cluster_id: this.cluster.id,
+      sender: this.id,
+      sender_model: this._selectModel(),
+    });
+  }
+
+  /**
+   * Publish agent lifecycle event to message bus (visible in zeroshot logs)
+   * @private
+   */
+  _publishLifecycle(event, details = {}) {
+    this._publish({
+      topic: 'AGENT_LIFECYCLE',
+      receiver: 'system',
+      content: {
+        text: `${this.id}: ${event}`,
+        data: {
+          event,
+          agent: this.id,
+          role: this.role,
+          state: this.state,
+          model: this._selectModel(),
+          ...details,
+        },
+      },
+    });
+  }
+
+  /**
+   * Select model based on current iteration and agent config
+   * @returns {string} Model name ('sonnet', 'opus', 'haiku')
+   * @private
+   */
+  _selectModel() {
+    // Backward compatibility: static model
+    if (this.modelConfig.type === 'static') {
+      return this.modelConfig.model;
+    }
+
+    // Dynamic rules: evaluate based on iteration
+    for (const rule of this.modelConfig.rules) {
+      if (this._matchesIterationRange(rule.iterations)) {
+        return rule.model;
+      }
+    }
+
+    // No match: fail fast
+    throw new Error(
+      `Agent ${this.id}: No model rule matched iteration ${this.iteration}. ` +
+        `Add a catch-all rule like { "iterations": "all", "model": "sonnet" }`
+    );
+  }
+
+  /**
+   * Check if current iteration matches the range pattern
+   * @param {string} pattern - e.g., "1", "1-3", "5+", "all"
+   * @returns {boolean}
+   * @private
+   */
+  _matchesIterationRange(pattern) {
+    if (pattern === 'all') return true;
+
+    const current = this.iteration;
+
+    // Exact match: "3"
+    if (/^\d+$/.test(pattern)) {
+      return current === parseInt(pattern);
+    }
+
+    // Range: "1-3"
+    const rangeMatch = pattern.match(/^(\d+)-(\d+)$/);
+    if (rangeMatch) {
+      const [, start, end] = rangeMatch;
+      return current >= parseInt(start) && current <= parseInt(end);
+    }
+
+    // Open-ended: "5+"
+    const openMatch = pattern.match(/^(\d+)\+$/);
+    if (openMatch) {
+      const [, start] = openMatch;
+      return current >= parseInt(start);
+    }
+
+    throw new Error(
+      `Agent ${this.id}: Invalid iteration pattern '${pattern}'. ` +
+        `Valid formats: "1", "1-3", "5+", "all"`
+    );
+  }
+
+  /**
+   * Select prompt based on current iteration and agent config
+   * @returns {string|null} System prompt string, or null if no prompt configured
+   * @private
+   */
+  _selectPrompt() {
+    const promptConfig = this.config.promptConfig;
+
+    // No prompt configured
+    if (!promptConfig) {
+      return null;
+    }
+
+    // Backward compatibility: static prompt
+    if (promptConfig.type === 'static') {
+      return promptConfig.system;
+    }
+
+    // Dynamic rules: evaluate based on iteration
+    for (const rule of promptConfig.rules) {
+      if (this._matchesIterationRange(rule.match)) {
+        return rule.system;
+      }
+    }
+
+    // No match: fail fast
+    throw new Error(
+      `Agent ${this.id}: No prompt rule matched iteration ${this.iteration}. ` +
+        `Add a catch-all rule like { "match": "all", "system": "..." }`
+    );
+  }
+
+  /**
+   * Start the agent (begin listening for triggers)
+   */
+  start() {
+    return lifecycleStart(this);
+  }
+
+  /**
+   * Stop the agent
+   */
+  stop() {
+    return lifecycleStop(this);
+  }
+
+  /**
+   * Handle incoming message
+   * @private
+   */
+  _handleMessage(message) {
+    return lifecycleHandleMessage(this, message);
+  }
+
+  /**
+   * Find trigger matching the message topic
+   * @private
+   */
+  _findMatchingTrigger(message) {
+    return findMatchingTrigger({
+      triggers: this.config.triggers,
+      message,
+    });
+  }
+
+  /**
+   * Evaluate trigger logic
+   * @private
+   */
+  _evaluateTrigger(trigger, message) {
+    const agent = {
+      id: this.id,
+      role: this.role,
+      iteration: this.iteration,
+      cluster_id: this.cluster.id,
+    };
+
+    return evaluateTrigger({
+      trigger,
+      message,
+      agent,
+      logicEngine: this.logicEngine,
+    });
+  }
+
+  /**
+   * Execute trigger action
+   * @private
+   */
+  _executeTriggerAction(trigger, message) {
+    return lifecycleExecuteTriggerAction(this, trigger, message);
+  }
+
+  /**
+   * Execute claude-zeroshots with built context
+   * Retries disabled by default. Set agent config `maxRetries` to enable (e.g., 3).
+   * @private
+   */
+  _executeTask(triggeringMessage) {
+    return lifecycleExecuteTask(this, triggeringMessage);
+  }
+
+  /**
+   * Build context from ledger based on contextStrategy
+   * @private
+   */
+  _buildContext(triggeringMessage) {
+    return buildContext({
+      id: this.id,
+      role: this.role,
+      iteration: this.iteration,
+      config: this.config,
+      messageBus: this.messageBus,
+      cluster: this.cluster,
+      lastTaskEndTime: this.lastTaskEndTime,
+      triggeringMessage,
+      selectedPrompt: this._selectPrompt(),
+    });
+  }
+
+  /**
+   * Spawn claude-zeroshots process and stream output via message bus
+   * @private
+   */
+  _spawnClaudeTask(context) {
+    return spawnClaudeTask(this, context);
+  }
+
+  /**
+   * Wait for task to be registered in ct storage
+   * @private
+   */
+  _waitForTaskReady(taskId, maxRetries = 10, delayMs = 200) {
+    return waitForTaskReady(this, taskId, maxRetries, delayMs);
+  }
+
+  /**
+   * Follow claude-zeroshots logs until completion, streaming to message bus
+   * Reads log file directly for reliable streaming
+   * @private
+   */
+  _followClaudeTaskLogs(taskId) {
+    return followClaudeTaskLogs(this, taskId);
+  }
+
+  /**
+   * Get path to claude-zeroshots executable
+   * @private
+   */
+  _getClaudeTasksPath() {
+    return getClaudeTasksPath();
+  }
+
+  /**
+   * Spawn claude-zeroshots inside Docker container (isolation mode)
+   * Runs Claude CLI inside the container for full isolation
+   * @private
+   */
+  _spawnClaudeTaskIsolated(context) {
+    return spawnClaudeTaskIsolated(this, context);
+  }
+
+  /**
+   * Kill current task
+   * @private
+   */
+  _killTask() {
+    return killTask(this);
+  }
+
+  /**
+   * Execute a hook
+   * THROWS on failure - no silent errors
+   * @private
+   */
+  _executeHook(hookName, context) {
+    const hook = this.config.hooks?.[hookName];
+    return executeHook({
+      hook,
+      agent: this,
+      message: context.triggeringMessage,
+      result: context.result,
+      messageBus: this.messageBus,
+      cluster: this.cluster,
+      orchestrator: this.orchestrator,
+    });
+  }
+
+  /**
+   * Parse agent output to extract structured result data
+   * GENERIC - returns whatever structured output the agent provides
+   * Works with any agent schema (planner, validator, worker, etc.)
+   * @private
+   */
+  _parseResultOutput(output) {
+    return parseResultOutput(this, output);
+  }
+
+  /**
+   * Resume agent task with context from previous failure
+   * Called by Orchestrator.resume() to continue where we left off
+   * @param {String} resumeContext - Context describing what to resume
+   */
+  async resume(resumeContext) {
+    if (!this.running) {
+      throw new Error(`Agent ${this.id} is not running. Start it first.`);
+    }
+
+    if (this.state !== 'idle') {
+      throw new Error(`Agent ${this.id} is busy (state: ${this.state}). Wait for current task.`);
+    }
+
+    this._log(`[${this.id}] Resuming task...`);
+
+    // Create a synthetic triggering message for resume
+    const triggeringMessage = {
+      cluster_id: this.cluster.id,
+      topic: 'AGENT_RESUME',
+      sender: 'system',
+      content: {
+        text: resumeContext,
+      },
+    };
+
+    // Execute the task with resume context
+    await this._executeTask(triggeringMessage);
+  }
+
+  /**
+   * Get current agent state
+   */
+  getState() {
+    return {
+      id: this.id,
+      role: this.role,
+      model: this._selectModel(),
+      state: this.state,
+      iteration: this.iteration,
+      maxIterations: this.maxIterations,
+      currentTask: this.currentTask ? true : false,
+      currentTaskId: this.currentTaskId,
+      pid: this.processPid,
+    };
+  }
+
+  /**
+   * Start monitoring agent output liveness
+   * Detects when agent produces no output for configured staleDuration
+   * @private
+   */
+  _startLivenessCheck() {
+    return lifecycleStartLivenessCheck(this);
+  }
+
+  /**
+   * Stop liveness monitoring
+   * @private
+   */
+  _stopLivenessCheck() {
+    return lifecycleStopLivenessCheck(this);
+  }
+}
+
+module.exports = AgentWrapper;

package/src/agents/git-pusher-agent.json

@@ -0,0 +1,20 @@
+{
+  "id": "git-pusher",
+  "role": "completion-detector",
+  "model": "sonnet",
+  "triggers": [
+    {
+      "topic": "VALIDATION_RESULT",
+      "logic": {
+        "engine": "javascript",
+        "script": "const validators = cluster.getAgentsByRole('validator'); const lastPush = ledger.findLast({ topic: 'IMPLEMENTATION_READY' }); if (!lastPush) return false; const results = ledger.query({ topic: 'VALIDATION_RESULT', since: lastPush.timestamp }); if (results.length < validators.length) return false; return results.every(r => r.content?.data?.approved === 'true' || r.content?.data?.approved === true);"
+      },
+      "action": "execute_task"
+    }
+  ],
+  "prompt": "🚨 CRITICAL: ALL VALIDATORS APPROVED. YOU MUST CREATE A PR AND GET IT MERGED. DO NOT STOP UNTIL THE PR IS MERGED. 🚨\n\n## MANDATORY STEPS - EXECUTE EACH ONE IN ORDER - DO NOT SKIP ANY STEP\n\n### STEP 1: Stage ALL changes (MANDATORY)\n```bash\ngit add -A\n```\nRun this command. Do not skip it.\n\n### STEP 2: Check what's staged\n```bash\ngit status\n```\nRun this. If nothing to commit, output JSON with pr_url: null and stop.\n\n### STEP 3: Commit the changes (MANDATORY if there are changes)\n```bash\ngit commit -m \"feat: implement #{{issue_number}} - {{issue_title}}\"\n```\nRun this command. Do not skip it.\n\n### STEP 4: Push to origin (MANDATORY)\n```bash\ngit push -u origin HEAD\n```\nRun this. If it fails, check the error and fix it.\n\n⚠️ AFTER PUSH YOU ARE NOT DONE! CONTINUE TO STEP 5! ⚠️\n\n### STEP 5: CREATE THE PR (MANDATORY - YOU MUST RUN THIS COMMAND)\n```bash\ngh pr create --title \"feat: {{issue_title}}\" --body \"Closes #{{issue_number}}\"\n```\n🚨 YOU MUST RUN `gh pr create`! Outputting a link is NOT creating a PR! 🚨\nThe push output shows a \"Create a pull request\" link - IGNORE IT.\nYou MUST run the `gh pr create` command above. Save the actual PR URL from the output.\n\n⚠️ AFTER PR CREATION YOU ARE NOT DONE! CONTINUE TO STEP 6! ⚠️\n\n### STEP 6: MERGE THE PR (MANDATORY - THIS IS NOT OPTIONAL)\n```bash\ngh pr merge --merge --auto\n```\nThis sets auto-merge. If it fails (e.g., no auto-merge enabled), try:\n```bash\ngh pr merge --merge\n```\n\n🚨 IF MERGE FAILS DUE TO CONFLICTS - YOU MUST RESOLVE THEM:\na) Pull latest main and rebase:\n   ```bash\n   git fetch origin main\n   git rebase origin/main\n   ```\nb) If conflicts appear - RESOLVE THEM IMMEDIATELY:\n   - Read the conflicting files\n   - Make intelligent decisions about what code to keep\n   - Edit the files to resolve conflicts\n   - `git add <resolved-files>`\n   - `git rebase --continue`\nc) Force push the resolved branch:\n   ```bash\n   git push --force-with-lease\n   ```\nd) Retry merge:\n   ```bash\n   gh pr merge --merge\n   ```\n\nREPEAT UNTIL MERGED. DO NOT GIVE UP. DO NOT SKIP. THE PR MUST BE MERGED.\nIf merge is blocked by CI, wait and retry. If blocked by reviews, set auto-merge.\n\n## CRITICAL RULES\n- Execute EVERY step in order (1, 2, 3, 4, 5, 6)\n- Do NOT skip git add -A\n- Do NOT skip git commit\n- Do NOT skip gh pr create - THE TASK IS NOT DONE UNTIL PR EXISTS\n- Do NOT skip gh pr merge - THE TASK IS NOT DONE UNTIL PR IS MERGED\n- If push fails, debug and fix it\n- If PR creation fails, debug and fix it\n- If merge fails, debug and fix it\n- DO NOT OUTPUT JSON UNTIL PR IS ACTUALLY MERGED\n- A link from git push is NOT a PR - you must run gh pr create\n\n## Final Output\nONLY after the PR is MERGED, output:\n```json\n{\"pr_url\": \"https://github.com/owner/repo/pull/123\", \"pr_number\": 123, \"merged\": true}\n```\n\nIf truly no changes exist, output:\n```json\n{\"pr_url\": null, \"pr_number\": null, \"merged\": false}\n```",
+  "output": {
+    "topic": "PR_CREATED",
+    "publishAfter": "CLUSTER_COMPLETE"
+  }
+}