@covibes/zeroshot 5.2.1 → 5.3.0

package/src/agent/agent-config.js

@@ -9,7 +9,9 @@
  * - maxModel ceiling enforcement at config time
  */
 
-const { loadSettings, validateModelAgainstMax } = require('../../lib/settings');
+const { loadSettings, validateModelAgainstMax, VALID_MODELS } = require('../../lib/settings');
+
+const VALID_LEVELS = ['level1', 'level2', 'level3'];
 
 // Default max iterations (high limit - let the user decide when to give up)
 const DEFAULT_MAX_ITERATIONS = 100;
@@ -58,39 +60,61 @@ function validateAgentConfig(config, options = {}) {
   }
 
   // Model configuration: support both static model and dynamic rules
-  // If no model specified, model is null - _selectModel() will use maxModel as default
+  // If no model specified, model is null - _selectModel() will use provider defaults
   let modelConfig;
   if (config.modelRules) {
     modelConfig = { type: 'rules', rules: config.modelRules };
   } else {
-    modelConfig = { type: 'static', model: config.model || null };
+    modelConfig = {
+      type: 'static',
+      model: config.model || null,
+      modelLevel: config.modelLevel || null,
+    };
   }
 
-  // COST CEILING ENFORCEMENT: Validate model(s) against maxModel at config time
+  // COST CEILING/FLOOR ENFORCEMENT: Validate model(s) against maxModel and minModel at config time
   // Catches violations EARLY (config load) instead of at runtime (iteration N)
   const settings = loadSettings();
   const maxModel = settings.maxModel || 'sonnet';
+  const minModel = settings.minModel || null;
+
+  if (modelConfig.type === 'static') {
+    if (modelConfig.model && VALID_MODELS.includes(modelConfig.model)) {
+      // Static model: validate once (legacy Claude models only)
+      try {
+        validateModelAgainstMax(modelConfig.model, maxModel, minModel);
+      } catch (error) {
+        throw new Error(`Agent "${config.id}": ${error.message}`);
+      }
+    }
 
-  if (modelConfig.type === 'static' && modelConfig.model) {
-    // Static model: validate once
-    try {
-      validateModelAgainstMax(modelConfig.model, maxModel);
-    } catch (error) {
-      throw new Error(`Agent "${config.id}": ${error.message}`);
+    if (modelConfig.modelLevel && !VALID_LEVELS.includes(modelConfig.modelLevel)) {
+      throw new Error(
+        `Agent "${config.id}": invalid modelLevel "${modelConfig.modelLevel}". ` +
+          `Valid: ${VALID_LEVELS.join(', ')}`
+      );
     }
   } else if (modelConfig.type === 'rules') {
     // Dynamic rules: validate ALL rules upfront (don't wait until iteration N)
     for (const rule of modelConfig.rules) {
-      if (rule.model) {
+      if (rule.model && VALID_MODELS.includes(rule.model)) {
         try {
-          validateModelAgainstMax(rule.model, maxModel);
+          validateModelAgainstMax(rule.model, maxModel, minModel);
         } catch {
           throw new Error(
             `Agent "${config.id}": modelRule "${rule.iterations}" requests "${rule.model}" ` +
-              `but maxModel is "${maxModel}". Either lower the rule's model or raise maxModel.`
+              `but maxModel is "${maxModel}"${minModel ? ` and minModel is "${minModel}"` : ''}. ` +
+              `Either adjust the rule's model or change maxModel/minModel settings.`
           );
         }
       }
+
+      if (rule.modelLevel && !VALID_LEVELS.includes(rule.modelLevel)) {
+        throw new Error(
+          `Agent "${config.id}": modelRule "${rule.iterations}" has invalid modelLevel ` +
+            `"${rule.modelLevel}". Valid: ${VALID_LEVELS.join(', ')}`
+        );
+      }
     }
   }
 

package/src/agent/agent-context-builder.js

@@ -13,6 +13,44 @@
 // Prevents "Prompt is too long" errors that kill tasks
 const MAX_CONTEXT_CHARS = 500000;
 
+/**
+ * Generate an example object from a JSON schema
+ * Used to show models a concrete example of expected output
+ *
+ * @param {object} schema - JSON schema
+ * @returns {object|null} Example object or null if generation fails
+ */
+function generateExampleFromSchema(schema) {
+  if (!schema || schema.type !== 'object' || !schema.properties) {
+    return null;
+  }
+
+  const example = {};
+
+  for (const [key, propSchema] of Object.entries(schema.properties)) {
+    if (propSchema.enum && propSchema.enum.length > 0) {
+      // Use first enum value as example
+      example[key] = propSchema.enum[0];
+    } else if (propSchema.type === 'string') {
+      example[key] = propSchema.description || `${key} value`;
+    } else if (propSchema.type === 'boolean') {
+      example[key] = true;
+    } else if (propSchema.type === 'number' || propSchema.type === 'integer') {
+      example[key] = 0;
+    } else if (propSchema.type === 'array') {
+      if (propSchema.items?.type === 'string') {
+        example[key] = [];
+      } else {
+        example[key] = [];
+      }
+    } else if (propSchema.type === 'object') {
+      example[key] = generateExampleFromSchema(propSchema) || {};
+    }
+  }
+
+  return example;
+}
+
 /**
  * Build execution context for an agent
  * @param {object} params - Context building parameters
@@ -91,7 +129,8 @@ function buildContext({
   // Add prompt from config (system prompt, instructions, output format)
   // If selectedPrompt is provided (iteration-based), use it directly
   // Otherwise fall back to legacy config.prompt handling
-  const promptText = selectedPrompt || (typeof config.prompt === 'string' ? config.prompt : config.prompt?.system);
+  const promptText =
+    selectedPrompt || (typeof config.prompt === 'string' ? config.prompt : config.prompt?.system);
 
   if (promptText) {
     context += `## Instructions\n\n${promptText}\n\n`;
@@ -103,7 +142,7 @@ function buildContext({
     );
   }
 
-  // Output format schema (if configured)
+  // Output format schema (if configured via legacy format)
   if (config.prompt?.outputFormat) {
     context += `## Output Schema (REQUIRED)\n\n`;
     context += `\`\`\`json\n${JSON.stringify(config.prompt.outputFormat.example, null, 2)}\n\`\`\`\n\n`;
@@ -116,6 +155,29 @@ function buildContext({
     context += '\n';
   }
 
+  // AUTO-INJECT JSON OUTPUT INSTRUCTIONS when jsonSchema is defined
+  // This ensures ALL agents with structured output schemas get explicit "output ONLY JSON" instructions
+  // Critical for less capable models (Codex, Gemini) that output prose without explicit instructions
+  if (config.jsonSchema && config.outputFormat === 'json') {
+    context += `## 🔴 OUTPUT FORMAT - JSON ONLY\n\n`;
+    context += `Your response must be ONLY valid JSON. No other text before or after.\n`;
+    context += `Start with { and end with }. Nothing else.\n\n`;
+    context += `Required schema:\n`;
+    context += `\`\`\`json\n${JSON.stringify(config.jsonSchema, null, 2)}\n\`\`\`\n\n`;
+
+    // Generate example from schema
+    const example = generateExampleFromSchema(config.jsonSchema);
+    if (example) {
+      context += `Example output:\n`;
+      context += `\`\`\`json\n${JSON.stringify(example, null, 2)}\n\`\`\`\n\n`;
+    }
+
+    context += `CRITICAL RULES:\n`;
+    context += `- Output ONLY the JSON object - no explanation, no thinking, no preamble\n`;
+    context += `- Use EXACTLY the enum values specified (case-sensitive)\n`;
+    context += `- Include ALL required fields\n\n`;
+  }
+
   // Add sources
   for (const source of strategy.sources) {
     // Resolve special 'since' values

package/src/agent/agent-hook-executor.js

@@ -22,7 +22,7 @@ const vm = require('vm');
  * @param {Object} params.orchestrator - Orchestrator instance
  * @returns {Promise<void>}
  */
-function executeHook(params) {
+async function executeHook(params) {
   const { hook, agent, message, result, cluster } = params;
 
   if (!hook) {
@@ -43,14 +43,14 @@ function executeHook(params) {
 
     if (hook.transform) {
       // NEW: Execute transform script to generate message
-      messageToPublish = executeTransform({
+      messageToPublish = await executeTransform({
         transform: hook.transform,
         context,
         agent,
       });
     } else {
       // Existing: Use template substitution
-      messageToPublish = substituteTemplate({
+      messageToPublish = await substituteTemplate({
         config: hook.config,
         context,
         agent,
@@ -77,9 +77,9 @@ function executeHook(params) {
  * @param {Object} params.transform - Transform configuration
  * @param {Object} params.context - Execution context
  * @param {Object} params.agent - Agent instance
- * @returns {Object} Message to publish
+ * @returns {Promise<Object>} Message to publish
  */
-function executeTransform(params) {
+async function executeTransform(params) {
   const { transform, context, agent } = params;
   const { engine, script } = transform;
 
@@ -93,7 +93,46 @@ function executeTransform(params) {
   let resultData = null;
 
   if (context.result?.output) {
-    resultData = agent._parseResultOutput(context.result.output);
+    try {
+      resultData = await agent._parseResultOutput(context.result.output);
+    } catch (parseError) {
+      // FAIL FAST: Result parsing failed - don't continue with null data
+      const taskId = context.result?.taskId || agent.currentTaskId || 'UNKNOWN';
+      console.error(`\n${'='.repeat(80)}`);
+      console.error(`🔴 TRANSFORM SCRIPT BLOCKED - RESULT PARSING FAILED`);
+      console.error(`${'='.repeat(80)}`);
+      console.error(`Agent: ${agent.id}, Role: ${agent.role}`);
+      console.error(`TaskID: ${taskId}`);
+      console.error(`Parse error: ${parseError.message}`);
+      console.error(`Output (last 500 chars): ${(context.result.output || '').slice(-500)}`);
+      console.error(`${'='.repeat(80)}\n`);
+      throw new Error(
+        `Transform script cannot run: result parsing failed. ` +
+          `Agent: ${agent.id}, Error: ${parseError.message}`
+      );
+    }
+
+    // DEFENSIVE: Validate result has expected fields if script accesses them
+    // Extract field names from script (e.g., result.complexity, result.taskType)
+    const accessedFields = [...script.matchAll(/result\.([a-zA-Z_]+)/g)].map((m) => m[1]);
+    const missingFields = accessedFields.filter((f) => resultData[f] === undefined);
+    if (missingFields.length > 0) {
+      const taskId = context.result?.taskId || agent.currentTaskId || 'UNKNOWN';
+      console.error(`\n${'='.repeat(80)}`);
+      console.error(`🔴 TRANSFORM SCRIPT BLOCKED - MISSING REQUIRED FIELDS`);
+      console.error(`${'='.repeat(80)}`);
+      console.error(`Agent: ${agent.id}, Role: ${agent.role}, TaskID: ${taskId}`);
+      console.error(`Script accesses: ${accessedFields.join(', ')}`);
+      console.error(`Missing from result: ${missingFields.join(', ')}`);
+      console.error(`Result keys: ${Object.keys(resultData).join(', ')}`);
+      console.error(`Result data: ${JSON.stringify(resultData, null, 2)}`);
+      console.error(`${'='.repeat(80)}\n`);
+      throw new Error(
+        `Transform script accesses undefined fields: ${missingFields.join(', ')}. ` +
+          `Agent ${agent.id} (task ${taskId}) output missing required fields. ` +
+          `Check agent's jsonSchema and output format.`
+      );
+    }
   } else if (scriptUsesResult) {
     const taskId = context.result?.taskId || agent.currentTaskId || 'UNKNOWN';
     const outputLength = (context.result?.output || '').length;
@@ -151,6 +190,40 @@ function executeTransform(params) {
     throw new Error(`Transform script result must have a 'content' property`);
   }
 
+  // CRITICAL: Extra validation for CLUSTER_OPERATIONS - this is the make-or-break message
+  // If this message is malformed, the cluster will hang forever
+  if (result.topic === 'CLUSTER_OPERATIONS') {
+    const operations = result.content?.data?.operations;
+    if (!operations) {
+      console.error(`\n${'='.repeat(80)}`);
+      console.error(`🔴 CLUSTER_OPERATIONS MALFORMED - MISSING OPERATIONS ARRAY`);
+      console.error(`${'='.repeat(80)}`);
+      console.error(`Agent: ${agent.id}`);
+      console.error(`Result: ${JSON.stringify(result, null, 2)}`);
+      console.error(`${'='.repeat(80)}\n`);
+      throw new Error(
+        `CLUSTER_OPERATIONS message missing operations array. ` +
+          `Agent ${agent.id} transform script returned invalid structure.`
+      );
+    }
+    if (!Array.isArray(operations)) {
+      throw new Error(`CLUSTER_OPERATIONS.operations must be an array, got: ${typeof operations}`);
+    }
+    if (operations.length === 0) {
+      throw new Error(`CLUSTER_OPERATIONS.operations is empty - no operations to execute`);
+    }
+
+    // Validate each operation has required 'action' field
+    for (let i = 0; i < operations.length; i++) {
+      const op = operations[i];
+      if (!op || !op.action) {
+        throw new Error(`CLUSTER_OPERATIONS.operations[${i}] missing required 'action' field`);
+      }
+    }
+
+    agent._log(`✅ CLUSTER_OPERATIONS validated: ${operations.length} operations`);
+  }
+
   return result;
 }
 
@@ -163,9 +236,9 @@ function executeTransform(params) {
  * @param {Object} params.context - Execution context
  * @param {Object} params.agent - Agent instance
  * @param {Object} params.cluster - Cluster object
- * @returns {Object} Substituted configuration
+ * @returns {Promise<Object>} Substituted configuration
  */
-function substituteTemplate(params) {
+async function substituteTemplate(params) {
   const { config, context, agent, cluster } = params;
 
   if (!config) {
@@ -243,7 +316,7 @@ function substituteTemplate(params) {
       );
     }
     // Parse result output - WILL THROW if no JSON block
-    resultData = agent._parseResultOutput(context.result.output);
+    resultData = await agent._parseResultOutput(context.result.output);
   }
 
   // Helper to escape a value for JSON string substitution

package/src/agent/agent-lifecycle.js

@@ -281,7 +281,7 @@ async function executeTask(agent, triggeringMessage) {
         console.log(`${'='.repeat(80)}\n`);
       }
 
-      // Spawn claude-zeroshots
+      // Spawn provider task
       agent.state = 'executing_task';
 
       // LOCK CONTENTION FIX: Add random jitter for validators to prevent thundering herd
@@ -292,14 +292,19 @@ async function executeTask(agent, triggeringMessage) {
       if (agent.role === 'validator' && !agent.testMode) {
         const jitterMs = Math.floor(Math.random() * 15000); // 0-15 seconds
         if (!agent.quiet) {
-          agent._log(`[Agent ${agent.id}] Adding ${Math.round(jitterMs / 1000)}s jitter to prevent lock contention`);
+          agent._log(
+            `[Agent ${agent.id}] Adding ${Math.round(jitterMs / 1000)}s jitter to prevent lock contention`
+          );
         }
         await new Promise((resolve) => setTimeout(resolve, jitterMs));
       }
 
+      const modelSpec = agent._resolveModelSpec ? agent._resolveModelSpec() : null;
       agent._publishLifecycle('TASK_STARTED', {
         iteration: agent.iteration,
         model: agent._selectModel(),
+        provider: agent._resolveProvider ? agent._resolveProvider() : 'claude',
+        modelSpec,
         triggeredBy: triggeringMessage.topic,
         triggerFrom: triggeringMessage.sender,
       });
@@ -352,16 +357,48 @@ async function executeTask(agent, triggeringMessage) {
         });
       }
 
-      // Execute onComplete hook
-      await executeHook({
-        hook: agent.config.hooks?.onComplete,
-        agent: agent,
-        message: triggeringMessage,
-        result: result,
-        messageBus: agent.messageBus,
-        cluster: agent.cluster,
-        orchestrator: agent.orchestrator,
-      });
+      // Execute onComplete hook WITH RETRY
+      // Hook failure shouldn't retry the entire task - just the hook
+      const hookMaxRetries = 3;
+      const hookBaseDelay = 1000;
+      let hookSuccess = false;
+
+      for (let hookAttempt = 1; hookAttempt <= hookMaxRetries && !hookSuccess; hookAttempt++) {
+        try {
+          await executeHook({
+            hook: agent.config.hooks?.onComplete,
+            agent: agent,
+            message: triggeringMessage,
+            result: result,
+            messageBus: agent.messageBus,
+            cluster: agent.cluster,
+            orchestrator: agent.orchestrator,
+          });
+          hookSuccess = true;
+        } catch (hookError) {
+          console.error(`\n${'='.repeat(80)}`);
+          console.error(
+            `🔴 HOOK EXECUTION FAILED - AGENT: ${agent.id} (Attempt ${hookAttempt}/${hookMaxRetries})`
+          );
+          console.error(`${'='.repeat(80)}`);
+          console.error(`Error: ${hookError.message}`);
+
+          if (hookAttempt < hookMaxRetries) {
+            const delay = hookBaseDelay * Math.pow(2, hookAttempt - 1);
+            console.error(`Will retry hook in ${delay}ms...`);
+            console.error(`${'='.repeat(80)}\n`);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+          } else {
+            console.error(`${'='.repeat(80)}\n`);
+            // All hook retries exhausted - throw to trigger task-level handling
+            throw new Error(
+              `Hook execution failed after ${hookMaxRetries} attempts. ` +
+                `Task completed successfully but hook could not publish result. ` +
+                `Original error: ${hookError.message}`
+            );
+          }
+        }
+      }
 
       // ✅ SUCCESS - exit retry loop
       return;
@@ -381,8 +418,10 @@ async function executeTask(agent, triggeringMessage) {
       if (isLockError) {
         // Lock contention - add significant jittered delay
         const lockDelay = 10000 + Math.floor(Math.random() * 20000); // 10-30 seconds
-        console.error(`⚠️ Lock contention detected - waiting ${Math.round(lockDelay / 1000)}s before retry`);
-        await new Promise(resolve => setTimeout(resolve, lockDelay));
+        console.error(
+          `⚠️ Lock contention detected - waiting ${Math.round(lockDelay / 1000)}s before retry`
+        );
+        await new Promise((resolve) => setTimeout(resolve, lockDelay));
       } else if (attempt < maxRetries) {
         console.error(`Will retry in ${baseDelay * Math.pow(2, attempt - 1)}ms...`);
       }