@covibes/zeroshot 5.2.1 → 5.3.0

package/src/agent/output-extraction.js

@@ -0,0 +1,200 @@
+/**
+ * Output Extraction Module - Multi-Provider JSON Extraction
+ *
+ * Clean extraction pipeline for structured JSON from AI provider outputs.
+ * Each provider has different output formats - this module normalizes them.
+ *
+ * Provider formats:
+ * - Claude: {"type":"result","result":{...}} or {"type":"result","structured_output":{...}}
+ * - Codex: Raw text in item.created events, turn.completed has NO result field
+ * - Gemini: Raw text in message events, result event may have NO result field
+ *
+ * Extraction priority (most specific → least specific):
+ * 1. Result wrapper with content (type:result + result/structured_output field)
+ * 2. Accumulated text from provider parser events
+ * 3. Markdown code block extraction
+ * 4. Direct JSON parse of entire output
+ */
+
+const { getProvider, parseChunkWithProvider } = require('../providers');
+
+/**
+ * Strip timestamp prefix from log lines.
+ * Format: [epochMs]content or [epochMs]{json...}
+ *
+ * @param {string} line - Raw log line
+ * @returns {string} Content without timestamp prefix
+ */
+function stripTimestamp(line) {
+  if (!line || typeof line !== 'string') return '';
+  const trimmed = line.trim().replace(/\r$/, '');
+  if (!trimmed) return '';
+  const match = trimmed.match(/^\[(\d{13})\](.*)$/);
+  return match ? match[2] : trimmed;
+}
+
+/**
+ * Strategy 1: Extract from result wrapper
+ * Handles Claude CLI format: {"type":"result","result":{...}}
+ *
+ * @param {string} output - Raw output
+ * @returns {object|null} Extracted JSON or null
+ */
+function extractFromResultWrapper(output) {
+  const lines = output.split('\n');
+
+  for (const line of lines) {
+    const content = stripTimestamp(line);
+    if (!content.startsWith('{')) continue;
+
+    try {
+      const obj = JSON.parse(content);
+
+      // Must be type:result WITH actual content
+      if (obj.type !== 'result') continue;
+
+      // Check structured_output first (standard CLI format)
+      if (obj.structured_output && typeof obj.structured_output === 'object') {
+        return obj.structured_output;
+      }
+
+      // Check result field - can be object or string
+      if (obj.result) {
+        if (typeof obj.result === 'object') {
+          return obj.result;
+        }
+
+        // Result is string - might contain markdown-wrapped JSON
+        if (typeof obj.result === 'string') {
+          const extracted = extractFromMarkdown(obj.result) || extractDirectJson(obj.result);
+          if (extracted) return extracted;
+        }
+      }
+    } catch {
+      // Not valid JSON, continue to next line
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Strategy 2: Extract from accumulated text events
+ * Handles non-Claude providers where JSON is in text content
+ *
+ * @param {string} output - Raw output
+ * @param {string} providerName - Provider name for parser selection
+ * @returns {object|null} Extracted JSON or null
+ */
+function extractFromTextEvents(output, providerName) {
+  const provider = getProvider(providerName);
+  const events = parseChunkWithProvider(provider, output);
+
+  // Accumulate all text events
+  const textContent = events
+    .filter((e) => e.type === 'text')
+    .map((e) => e.text)
+    .join('');
+
+  if (!textContent.trim()) return null;
+
+  // Try parsing accumulated text as JSON
+  return extractDirectJson(textContent) || extractFromMarkdown(textContent);
+}
+
+/**
+ * Strategy 3: Extract JSON from markdown code block
+ * Handles: ```json\n{...}\n```
+ *
+ * @param {string} text - Text that may contain markdown
+ * @returns {object|null} Extracted JSON or null
+ */
+function extractFromMarkdown(text) {
+  if (!text) return null;
+
+  // Match ```json ... ``` with any whitespace
+  const match = text.match(/```json\s*([\s\S]*?)```/);
+  if (!match) return null;
+
+  try {
+    const parsed = JSON.parse(match[1].trim());
+    if (typeof parsed === 'object' && parsed !== null) {
+      return parsed;
+    }
+  } catch {
+    // Invalid JSON in markdown block
+  }
+
+  return null;
+}
+
+/**
+ * Strategy 4: Direct JSON parse
+ * Handles raw JSON output (single-line or multi-line)
+ *
+ * @param {string} text - Text to parse
+ * @returns {object|null} Parsed JSON or null
+ */
+function extractDirectJson(text) {
+  if (!text) return null;
+
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {
+    // Not valid JSON
+  }
+
+  return null;
+}
+
+/**
+ * Main extraction function - tries all strategies in priority order
+ *
+ * @param {string} output - Raw output from AI provider CLI
+ * @param {string} providerName - Provider name ('claude', 'codex', 'gemini')
+ * @returns {object|null} Extracted JSON object or null if extraction failed
+ */
+function extractJsonFromOutput(output, providerName = 'claude') {
+  if (!output || typeof output !== 'string') return null;
+
+  const trimmedOutput = output.trim();
+  if (!trimmedOutput) return null;
+
+  // Check for fatal error indicators
+  if (trimmedOutput.includes('Task not found') || trimmedOutput.includes('Process terminated')) {
+    return null;
+  }
+
+  // Strategy 1: Result wrapper (Claude format)
+  const fromWrapper = extractFromResultWrapper(trimmedOutput);
+  if (fromWrapper) return fromWrapper;
+
+  // Strategy 2: Text events (non-Claude providers)
+  const fromText = extractFromTextEvents(trimmedOutput, providerName);
+  if (fromText) return fromText;
+
+  // Strategy 3: Markdown extraction
+  const fromMarkdown = extractFromMarkdown(trimmedOutput);
+  if (fromMarkdown) return fromMarkdown;
+
+  // Strategy 4: Direct JSON parse (raw output)
+  const fromDirect = extractDirectJson(trimmedOutput);
+  if (fromDirect) return fromDirect;
+
+  return null;
+}
+
+module.exports = {
+  extractJsonFromOutput,
+  extractFromResultWrapper,
+  extractFromTextEvents,
+  extractFromMarkdown,
+  extractDirectJson,
+  stripTimestamp,
+};

package/src/agent/output-reformatter.js

@@ -0,0 +1,175 @@
+/**
+ * Output Reformatter - Convert non-JSON output to valid JSON
+ *
+ * When an LLM outputs markdown/text instead of JSON despite schema instructions,
+ * this module attempts to extract/reformat the content into valid JSON.
+ *
+ * STATUS: SDK NOT IMPLEMENTED - Reformatting is not available.
+ * This module exists for future extension when SDK support is added.
+ *
+ * To enable reformatting:
+ * 1. Implement SDK support in the provider (getSDKEnvVar, callSimple)
+ * 2. The reformatOutput() function will then work automatically
+ */
+
+const DEFAULT_MAX_ATTEMPTS = 3;
+
+/**
+ * Build the reformatting prompt
+ *
+ * @param {string} rawOutput - The non-JSON output to reformat
+ * @param {Object} schema - Target JSON schema
+ * @param {string|null} previousError - Error from previous attempt (for feedback)
+ * @returns {string} The prompt for the reformatting model
+ */
+function buildReformatPrompt(rawOutput, schema, previousError = null) {
+  const schemaStr = JSON.stringify(schema, null, 2);
+  // Truncate long outputs to avoid context limits
+  const truncatedOutput = rawOutput.length > 4000 ? rawOutput.slice(-4000) : rawOutput;
+
+  let prompt = `Convert this text into a JSON object matching the schema.
+
+## SCHEMA
+\`\`\`json
+${schemaStr}
+\`\`\`
+
+## TEXT TO CONVERT
+\`\`\`
+${truncatedOutput}
+\`\`\`
+
+## RULES
+- Output ONLY the JSON object
+- NO markdown code blocks
+- NO explanations
+- Start with { end with }
+- Match ALL required fields from schema`;
+
+  if (previousError) {
+    prompt += `
+
+## PREVIOUS ATTEMPT FAILED
+Error: ${previousError}
+Fix this issue in your response.`;
+  }
+
+  return prompt;
+}
+
+/**
+ * Attempt to reformat non-JSON output into valid JSON
+ *
+ * STATUS: SDK NOT IMPLEMENTED - This function always throws.
+ * When SDK support is added to providers, this will work automatically.
+ *
+ * @param {Object} options
+ * @param {string} options.rawOutput - The non-JSON output to reformat
+ * @param {Object} options.schema - Target JSON schema
+ * @param {string} options.providerName - Provider name (claude, codex, gemini)
+ * @param {number} [options.maxAttempts=3] - Maximum reformatting attempts
+ * @param {Function} [options.onAttempt] - Callback for each attempt (attempt, error)
+ * @returns {Promise<Object>} The reformatted JSON object
+ * @throws {Error} Always throws - SDK not implemented
+ */
+function reformatOutput({
+  rawOutput,
+  schema: _schema,
+  providerName,
+  maxAttempts: _maxAttempts = DEFAULT_MAX_ATTEMPTS,
+  onAttempt: _onAttempt,
+}) {
+  // SDK not implemented - reformatting not available
+  // When SDK support is added, uncomment the implementation below
+  return Promise.reject(
+    new Error(
+      `Output reformatting not available: SDK not implemented for provider "${providerName}". ` +
+        `Agent output must be valid JSON. Raw output (last 200 chars): ${(rawOutput || '').slice(-200)}`
+    )
+  );
+
+  // FUTURE: When SDK support is added to providers, uncomment this:
+  /*
+  const { getProvider } = require('../providers');
+  const provider = getProvider(providerName);
+
+  let lastError = null;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    if (onAttempt) {
+      onAttempt(attempt, lastError);
+    }
+
+    const prompt = buildReformatPrompt(rawOutput, schema, lastError);
+
+    try {
+      const result = await provider.callSimple(prompt, {
+        level: 'level1',
+        maxTokens: 2000,
+      });
+
+      if (!result?.success) {
+        lastError = result?.error || 'API call failed';
+        continue;
+      }
+
+      if (!result?.text) {
+        lastError = 'Empty response from reformatting model';
+        continue;
+      }
+
+      const parsed = extractJsonFromOutput(result.text, providerName);
+
+      if (!parsed) {
+        lastError = 'Could not extract JSON from reformatted output';
+        continue;
+      }
+
+      const validationError = validateAgainstSchema(parsed, schema);
+      if (validationError) {
+        lastError = validationError;
+        continue;
+      }
+
+      return parsed;
+    } catch (err) {
+      lastError = err.message;
+    }
+  }
+
+  throw new Error(
+    `Failed to reformat output after ${maxAttempts} attempts. Last error: ${lastError}`
+  );
+  */
+}
+
+/**
+ * Validate parsed output against JSON schema
+ *
+ * @param {Object} parsed - Parsed JSON object
+ * @param {Object} schema - JSON schema to validate against
+ * @returns {string|null} Error message if validation failed, null if valid
+ */
+function validateAgainstSchema(parsed, schema) {
+  const Ajv = require('ajv');
+  const ajv = new Ajv({ allErrors: true, strict: false });
+  const validate = ajv.compile(schema);
+  const valid = validate(parsed);
+
+  if (!valid) {
+    const errors = (validate.errors || [])
+      .slice(0, 3)
+      .map((e) => `${e.instancePath || '#'} ${e.message}`)
+      .join('; ');
+    return errors || 'Schema validation failed';
+  }
+
+  return null;
+}
+
+module.exports = {
+  reformatOutput,
+  buildReformatPrompt,
+  validateAgainstSchema,
+  DEFAULT_MAX_ATTEMPTS,
+};

package/src/agent/schema-utils.js

@@ -0,0 +1,111 @@
+/**
+ * Schema utilities for normalizing LLM output before validation.
+ *
+ * PROBLEM: LLMs (Claude, Gemini, Codex) via any interface (CLI, API) may return
+ * enum values that don't exactly match the schema (e.g., "simple" vs "SIMPLE").
+ *
+ * SOLUTION: Normalize enum values BEFORE validation. Provider-agnostic.
+ */
+
+/**
+ * Normalize enum values in parsed JSON to match schema definitions.
+ *
+ * Handles:
+ * - Case mismatches: "simple" → "SIMPLE"
+ * - Whitespace: " SIMPLE " → "SIMPLE"
+ * - Common variations: "bug" → "DEBUG", "fix" → "DEBUG"
+ *
+ * @param {Object} result - Parsed JSON result from LLM
+ * @param {Object} schema - JSON schema with enum definitions
+ * @returns {Object} Normalized result (mutates and returns same object)
+ */
+function normalizeEnumValues(result, schema) {
+  if (!result || typeof result !== 'object' || !schema?.properties) {
+    return result;
+  }
+
+  for (const [key, propSchema] of Object.entries(schema.properties)) {
+    if (propSchema.enum && typeof result[key] === 'string') {
+      let value = result[key].trim().toUpperCase();
+
+      // DETECT: Model copied the enum list instead of choosing (e.g., "TRIVIAL|SIMPLE|STANDARD")
+      if (value.includes('|')) {
+        const parts = value.split('|').map((p) => p.trim());
+        // Check if this looks like the enum list was copied verbatim
+        const matchCount = parts.filter((p) => propSchema.enum.includes(p)).length;
+        if (matchCount >= 2) {
+          // Model copied the format - pick the first valid option and warn
+          const firstValid = parts.find((p) => propSchema.enum.includes(p));
+          if (firstValid) {
+            console.warn(
+              `⚠️  Model copied enum format instead of choosing. Field "${key}" had "${result[key]}", using "${firstValid}"`
+            );
+            value = firstValid;
+          }
+        }
+      }
+
+      // Find exact match (case-insensitive)
+      const match = propSchema.enum.find((e) => e.toUpperCase() === value);
+      if (match) {
+        result[key] = match;
+        continue;
+      }
+
+      // Common variations mapping
+      const variations = {
+        // taskType variations
+        BUG: 'DEBUG',
+        FIX: 'DEBUG',
+        BUGFIX: 'DEBUG',
+        BUG_FIX: 'DEBUG',
+        INVESTIGATE: 'DEBUG',
+        TROUBLESHOOT: 'DEBUG',
+        IMPLEMENT: 'TASK',
+        BUILD: 'TASK',
+        CREATE: 'TASK',
+        ADD: 'TASK',
+        FEATURE: 'TASK',
+        QUESTION: 'INQUIRY',
+        ASK: 'INQUIRY',
+        EXPLORE: 'INQUIRY',
+        RESEARCH: 'INQUIRY',
+        UNDERSTAND: 'INQUIRY',
+        // complexity variations
+        EASY: 'TRIVIAL',
+        BASIC: 'SIMPLE',
+        MINOR: 'SIMPLE',
+        MODERATE: 'STANDARD',
+        MEDIUM: 'STANDARD',
+        NORMAL: 'STANDARD',
+        HARD: 'STANDARD',
+        COMPLEX: 'CRITICAL',
+        RISKY: 'CRITICAL',
+        HIGH_RISK: 'CRITICAL',
+        DANGEROUS: 'CRITICAL',
+      };
+
+      if (variations[value] && propSchema.enum.includes(variations[value])) {
+        result[key] = variations[value];
+      }
+    }
+
+    // Recursively handle nested objects
+    if (propSchema.type === 'object' && propSchema.properties && result[key]) {
+      normalizeEnumValues(result[key], propSchema);
+    }
+
+    // Handle arrays of objects
+    if (propSchema.type === 'array' && propSchema.items?.properties && Array.isArray(result[key])) {
+      for (const item of result[key]) {
+        normalizeEnumValues(item, propSchema.items);
+      }
+    }
+  }
+
+  return result;
+}
+
+module.exports = {
+  normalizeEnumValues,
+};

package/src/agent-wrapper.js

@@ -13,6 +13,8 @@
 const LogicEngine = require('./logic-engine');
 const { validateAgentConfig } = require('./agent/agent-config');
 const { loadSettings, validateModelAgainstMax } = require('../lib/settings');
+const { normalizeProviderName } = require('../lib/provider-names');
+const { getProvider } = require('./providers');
 const { buildContext } = require('./agent/agent-context-builder');
 const { findMatchingTrigger, evaluateTrigger } = require('./agent/agent-trigger-evaluator');
 const { executeHook } = require('./agent/agent-hook-executor');
@@ -87,9 +89,12 @@ class AgentWrapper {
       // TaskRunner DI - create mockSpawnFn wrapper
       const taskRunner = options.taskRunner;
       this.mockSpawnFn = (args, { context }) => {
+        const spec = this._resolveModelSpec();
         return taskRunner.run(context, {
           agentId: this.id,
           model: this._selectModel(),
+          modelSpec: spec,
+          provider: this._resolveProvider(),
         });
       };
     } else {
@@ -116,6 +121,90 @@ class AgentWrapper {
     }
   }
 
+  _resolveProvider() {
+    const settings = loadSettings();
+    const clusterConfig = this.cluster?.config || {};
+
+    const resolved =
+      clusterConfig.forceProvider ||
+      this.config.provider ||
+      clusterConfig.defaultProvider ||
+      settings.defaultProvider ||
+      'claude';
+
+    return normalizeProviderName(resolved) || 'claude';
+  }
+
+  _resolveModelSpec() {
+    const settings = loadSettings();
+    const providerName = this._resolveProvider();
+    const provider = getProvider(providerName);
+    const clusterConfig = this.cluster?.config || {};
+    const providerSettings = settings.providerSettings?.[providerName] || {};
+    const levelOverrides = providerSettings.levelOverrides || {};
+    const minLevel = providerSettings.minLevel;
+    const maxLevel = providerSettings.maxLevel;
+    const forcedLevel =
+      clusterConfig.forceProvider === providerName ? clusterConfig.forceLevel : null;
+
+    const applyReasoningOverride = (spec, override) => {
+      if (!override) return spec;
+      return { ...spec, reasoningEffort: override };
+    };
+
+    if (this.modelConfig.type === 'rules') {
+      for (const rule of this.modelConfig.rules) {
+        if (this._matchesIterationRange(rule.iterations)) {
+          if (rule.model) {
+            return {
+              level: 'custom',
+              model: rule.model,
+              reasoningEffort: rule.reasoningEffort || this.config.reasoningEffort,
+            };
+          }
+          if (rule.modelLevel) {
+            const level = provider.validateLevel(rule.modelLevel, minLevel, maxLevel);
+            const spec = provider.resolveModelSpec(level, levelOverrides);
+            return applyReasoningOverride(
+              { ...spec, level },
+              rule.reasoningEffort || this.config.reasoningEffort
+            );
+          }
+        }
+      }
+
+      throw new Error(
+        `Agent ${this.id}: No model rule matched iteration ${this.iteration}. ` +
+          `Add a catch-all rule like { "iterations": "all", "modelLevel": "level2" }`
+      );
+    }
+
+    if (this.modelConfig.model) {
+      return {
+        level: 'custom',
+        model: this.modelConfig.model,
+        reasoningEffort: this.config.reasoningEffort,
+      };
+    }
+
+    if (forcedLevel) {
+      const level = provider.validateLevel(forcedLevel, minLevel, maxLevel);
+      const spec = provider.resolveModelSpec(level, levelOverrides);
+      return applyReasoningOverride({ ...spec, level }, this.config.reasoningEffort);
+    }
+
+    if (this.modelConfig.modelLevel) {
+      const level = provider.validateLevel(this.modelConfig.modelLevel, minLevel, maxLevel);
+      const spec = provider.resolveModelSpec(level, levelOverrides);
+      return applyReasoningOverride({ ...spec, level }, this.config.reasoningEffort);
+    }
+
+    const defaultLevel = providerSettings.defaultLevel || provider.getDefaultLevel();
+    const level = provider.validateLevel(defaultLevel, minLevel, maxLevel);
+    const spec = provider.resolveModelSpec(level, levelOverrides);
+    return applyReasoningOverride({ ...spec, level }, this.config.reasoningEffort);
+  }
+
   /**
    * Publish a message to the message bus, always including sender_model
    * @private
@@ -126,6 +215,7 @@ class AgentWrapper {
       cluster_id: this.cluster.id,
       sender: this.id,
       sender_model: this._selectModel(),
+      sender_provider: this._resolveProvider(),
     });
   }
 
@@ -145,6 +235,7 @@ class AgentWrapper {
           role: this.role,
           state: this.state,
           model: this._selectModel(),
+          provider: this._resolveProvider(),
           ...details,
         },
       },
@@ -153,44 +244,21 @@ class AgentWrapper {
 
   /**
    * Select model based on current iteration and agent config
-   * Enforces maxModel ceiling from settings
-   * @returns {string} Model name ('sonnet', 'opus', 'haiku')
+   * Enforces legacy maxModel/minModel for Claude's haiku/sonnet/opus
+   * @returns {string|null}
    * @private
    */
   _selectModel() {
+    const spec = this._resolveModelSpec();
     const settings = loadSettings();
     const maxModel = settings.maxModel || 'sonnet';
+    const minModel = settings.minModel || null;
 
-    let requestedModel = null;
-
-    // Get requested model from config
-    if (this.modelConfig.type === 'static') {
-      requestedModel = this.modelConfig.model;
-    } else if (this.modelConfig.type === 'rules') {
-      // Dynamic rules: evaluate based on iteration
-      for (const rule of this.modelConfig.rules) {
-        if (this._matchesIterationRange(rule.iterations)) {
-          requestedModel = rule.model;
-          break;
-        }
-      }
-
-      // No match for rules: fail fast (config error)
-      if (!requestedModel) {
-        throw new Error(
-          `Agent ${this.id}: No model rule matched iteration ${this.iteration}. ` +
-            `Add a catch-all rule like { "iterations": "all", "model": "sonnet" }`
-        );
-      }
-    }
-
-    // If no model specified (neither static nor rules), use maxModel as default
-    if (!requestedModel) {
-      return maxModel;
+    if (spec.model && ['opus', 'sonnet', 'haiku'].includes(spec.model)) {
+      return validateModelAgainstMax(spec.model, maxModel, minModel);
     }
 
-    // Enforce ceiling - will throw if requestedModel > maxModel
-    return validateModelAgainstMax(requestedModel, maxModel);
+    return spec.model || null;
   }
 
   /**
@@ -424,6 +492,7 @@ class AgentWrapper {
    * 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.)
+   * Falls back to reformatting if extraction fails
    * @private
    */
   _parseResultOutput(output) {
@@ -464,10 +533,13 @@ class AgentWrapper {
    * Get current agent state
    */
   getState() {
+    const modelSpec = this._resolveModelSpec();
     return {
       id: this.id,
       role: this.role,
       model: this._selectModel(),
+      provider: this._resolveProvider(),
+      modelSpec,
       state: this.state,
       iteration: this.iteration,
       maxIterations: this.maxIterations,

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

@@ -1,7 +1,7 @@
 {
   "id": "git-pusher",
   "role": "completion-detector",
-  "model": "sonnet",
+  "modelLevel": "level2",
   "triggers": [
     {
       "topic": "VALIDATION_RESULT",