@the-open-engine/zeroshot 6.38.0 → 6.39.0

package/src/agent/rate-limit-backoff.js

@@ -1,82 +1,39 @@
-/**
- * Rate-limit-aware backoff for API retries
- *
- * Rate limit errors (429, capacity exhausted, quota exceeded) need LONGER delays
- * than transient errors (timeouts, network issues).
- *
- * - Regular errors: 2s base, exponential backoff up to 30s
- * - Rate limits: 30s base, exponential backoff up to 5 minutes
- * - Retry-After header: Honored if present (capped at 5 min)
- */
-
-/**
- * Check if error is a rate limit error
- * @param {Error|string} error - Error object or message
- * @returns {boolean} True if this is a rate limit error
- */
+"use strict";
+const crypto = require("node:crypto");
+function sampleJitter() {
+    const range = 0x1_0000_0000;
+    return crypto.randomInt(range) / range;
+}
+/** Check if an error represents a rate limit. */
 function isRateLimitError(error) {
-  const msg = error?.message || String(error);
-  return /\b429\b|rate.?limit|too many requests|no capacity|quota.?exceeded|resource.?exhausted/i.test(
-    msg
-  );
+    const msg = error instanceof Error ? error.message || String(error) : String(error);
+    return /\b429\b|rate.?limit|too many requests|no capacity|quota.?exceeded|resource.?exhausted/i.test(msg);
 }
-
-/**
- * Parse Retry-After from error message
- * Looks for patterns like "Retry-After: 120" or "retry after 120 seconds"
- * @param {Error} error - Error object
- * @returns {number|null} Seconds to wait, or null if not found
- */
+/** Parse a Retry-After delay in seconds from an error message. */
 function parseRetryAfter(error) {
-  const msg = error?.message || '';
-  // Match "Retry-After: 120" or "retry after 120" (seconds)
-  const match = msg.match(/retry.?after[:\s]+(\d+)/i);
-  return match ? parseInt(match[1], 10) : null;
+    const msg = error?.message || '';
+    const match = /retry.?after[:\s]+(\d+)/i.exec(msg);
+    const retryAfterSeconds = match?.[1];
+    return retryAfterSeconds ? parseInt(retryAfterSeconds, 10) : null;
 }
-
-/**
- * Calculate delay for retry with rate-limit awareness
- *
- * Rate limit errors get 30s base delay instead of 2s.
- * Regular errors use exponential backoff from 2s base.
- *
- * @param {Error} error - The error that occurred
- * @param {number} attempt - Current attempt number (1-based)
- * @param {Object} settings - Settings with backoff config
- * @param {number} [settings.backoffBaseMs=2000] - Base delay for regular errors
- * @param {number} [settings.backoffMaxMs=30000] - Max delay for regular errors
- * @param {number} [settings.jitterFactor=0.2] - Jitter factor (±20%)
- * @returns {number} Delay in milliseconds
- */
+/** Calculate a retry delay with rate-limit awareness. */
 function calculateRateLimitDelay(error, attempt, settings = {}) {
-  const baseDelay = settings.backoffBaseMs ?? 2000;
-  const maxDelay = settings.backoffMaxMs ?? 30000;
-  const jitter = settings.jitterFactor ?? 0.2;
-
-  // Check for Retry-After header in error message
-  const retryAfter = parseRetryAfter(error);
-  if (retryAfter) {
-    // Honor Retry-After but cap at 5 minutes
-    return Math.min(retryAfter * 1000, 300000);
-  }
-
-  // Rate limits get 30s base, others get normal base
-  const isRateLimit = isRateLimitError(error);
-  const effectiveBase = isRateLimit ? 30000 : baseDelay;
-
-  // Exponential: base * 2^(attempt-1)
-  let delay = effectiveBase * Math.pow(2, attempt - 1);
-
-  // Cap at appropriate max (5 min for rate limits, settings max for others)
-  delay = Math.min(delay, isRateLimit ? 300000 : maxDelay);
-
-  // Add jitter (±jitterFactor)
-  const jitterAmount = delay * jitter * (Math.random() * 2 - 1);
-  return Math.round(delay + jitterAmount);
+    const baseDelay = settings.backoffBaseMs ?? 2000;
+    const maxDelay = settings.backoffMaxMs ?? 30000;
+    const jitter = settings.jitterFactor ?? 0.2;
+    const retryAfter = parseRetryAfter(error);
+    if (retryAfter) {
+        return Math.min(retryAfter * 1000, 300000);
+    }
+    const isRateLimit = isRateLimitError(error);
+    const effectiveBase = isRateLimit ? 30000 : baseDelay;
+    let delay = effectiveBase * Math.pow(2, attempt - 1);
+    delay = Math.min(delay, isRateLimit ? 300000 : maxDelay);
+    const jitterAmount = delay * jitter * (sampleJitter() * 2 - 1);
+    return Math.round(delay + jitterAmount);
 }
-
 module.exports = {
-  calculateRateLimitDelay,
-  isRateLimitError,
-  parseRetryAfter,
+    calculateRateLimitDelay,
+    isRateLimitError,
+    parseRetryAfter,
 };

package/src/agent/rate-limit-backoff.ts

@@ -0,0 +1,71 @@
+import crypto = require('node:crypto');
+
+/**
+ * Rate-limit-aware backoff for API retries
+ *
+ * Rate limit errors (429, capacity exhausted, quota exceeded) need LONGER delays
+ * than transient errors (timeouts, network issues).
+ *
+ * - Regular errors: 2s base, exponential backoff up to 30s
+ * - Rate limits: 30s base, exponential backoff up to 5 minutes
+ * - Retry-After header: Honored if present (capped at 5 min)
+ */
+
+type RateLimitError = Error | string | null | undefined;
+
+interface BackoffSettings {
+  backoffBaseMs?: number;
+  backoffMaxMs?: number;
+  jitterFactor?: number;
+}
+
+function sampleJitter(): number {
+  const range = 0x1_0000_0000;
+  return crypto.randomInt(range) / range;
+}
+
+/** Check if an error represents a rate limit. */
+function isRateLimitError(error: RateLimitError): boolean {
+  const msg = error instanceof Error ? error.message || String(error) : String(error);
+  return /\b429\b|rate.?limit|too many requests|no capacity|quota.?exceeded|resource.?exhausted/i.test(
+    msg
+  );
+}
+
+/** Parse a Retry-After delay in seconds from an error message. */
+function parseRetryAfter(error: Error | null | undefined): number | null {
+  const msg = error?.message || '';
+  const match = /retry.?after[:\s]+(\d+)/i.exec(msg);
+  const retryAfterSeconds = match?.[1];
+  return retryAfterSeconds ? parseInt(retryAfterSeconds, 10) : null;
+}
+
+/** Calculate a retry delay with rate-limit awareness. */
+function calculateRateLimitDelay(
+  error: Error,
+  attempt: number,
+  settings: BackoffSettings = {}
+): number {
+  const baseDelay = settings.backoffBaseMs ?? 2000;
+  const maxDelay = settings.backoffMaxMs ?? 30000;
+  const jitter = settings.jitterFactor ?? 0.2;
+
+  const retryAfter = parseRetryAfter(error);
+  if (retryAfter) {
+    return Math.min(retryAfter * 1000, 300000);
+  }
+
+  const isRateLimit = isRateLimitError(error);
+  const effectiveBase = isRateLimit ? 30000 : baseDelay;
+  let delay = effectiveBase * Math.pow(2, attempt - 1);
+  delay = Math.min(delay, isRateLimit ? 300000 : maxDelay);
+
+  const jitterAmount = delay * jitter * (sampleJitter() * 2 - 1);
+  return Math.round(delay + jitterAmount);
+}
+
+export = {
+  calculateRateLimitDelay,
+  isRateLimitError,
+  parseRetryAfter,
+};

package/src/agent/schema-utils.js

@@ -1,146 +1,106 @@
+"use strict";
 /**
  * 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.
+ * LLMs may return enum values that do not exactly match the schema. Normalize
+ * those values before validation without depending on a specific provider.
  */
-
 const ENUM_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',
+    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',
+    EASY: 'TRIVIAL',
+    BASIC: 'SIMPLE',
+    MINOR: 'SIMPLE',
+    MODERATE: 'STANDARD',
+    MEDIUM: 'STANDARD',
+    NORMAL: 'STANDARD',
+    HARD: 'STANDARD',
+    COMPLEX: 'CRITICAL',
+    RISKY: 'CRITICAL',
+    HIGH_RISK: 'CRITICAL',
+    DANGEROUS: 'CRITICAL',
 };
-
-/**
- * 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 isObjectRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/** Normalize enum values in parsed JSON, mutating and returning the same value. */
 function normalizeEnumValues(result, schema) {
-  if (!result || typeof result !== 'object' || !schema?.properties) {
-    return result;
-  }
-
-  for (const [key, propSchema] of Object.entries(schema.properties)) {
-    const matched = normalizeEnumValue({
-      result,
-      key,
-      propSchema,
-    });
-    if (matched) {
-      continue;
+    if (!isObjectRecord(result) || !schema?.properties) {
+        return result;
+    }
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+        const matched = normalizeEnumValue({ result, key, propSchema });
+        if (matched) {
+            continue;
+        }
+        normalizeNestedValues(result, propSchema, key);
     }
-
-    // Recursively handle nested objects
-    normalizeNestedValues(result, propSchema, key);
-  }
-
-  return result;
+    return result;
 }
-
 function normalizeEnumValue({ result, key, propSchema }) {
-  if (!propSchema.enum || typeof result[key] !== 'string') {
+    const rawValue = result[key];
+    const enumValues = propSchema.enum;
+    if (!enumValues || typeof rawValue !== 'string') {
+        return false;
+    }
+    let value = rawValue.trim().toUpperCase();
+    value = normalizeEnumCopyValue(value, enumValues, key, rawValue);
+    const match = findEnumMatch(enumValues, value);
+    if (match) {
+        result[key] = match;
+        return true;
+    }
+    const variation = ENUM_VARIATIONS[value];
+    if (variation && enumValues.includes(variation)) {
+        result[key] = variation;
+    }
     return false;
-  }
-
-  const rawValue = result[key];
-  let value = rawValue.trim().toUpperCase();
-  value = normalizeEnumCopyValue(value, propSchema.enum, key, rawValue);
-
-  // Find exact match (case-insensitive)
-  const match = findEnumMatch(propSchema.enum, value);
-  if (match) {
-    result[key] = match;
-    return true;
-  }
-
-  // Common variations mapping
-  const variation = ENUM_VARIATIONS[value];
-  if (variation && propSchema.enum.includes(variation)) {
-    result[key] = variation;
-  }
-
-  return false;
 }
-
 function normalizeEnumCopyValue(value, enumValues, key, rawValue) {
-  // DETECT: Model copied the enum list instead of choosing (e.g., "TRIVIAL|SIMPLE|STANDARD")
-  if (!value.includes('|')) {
-    return value;
-  }
-
-  const parts = value.split('|').map((p) => p.trim());
-  // Check if this looks like the enum list was copied verbatim
-  const matchCount = parts.filter((p) => enumValues.includes(p)).length;
-  if (matchCount < 2) {
-    return value;
-  }
-
-  // Model copied the format - pick the first valid option and warn
-  const firstValid = parts.find((p) => enumValues.includes(p));
-  if (!firstValid) {
-    return value;
-  }
-
-  console.warn(
-    `⚠️  Model copied enum format instead of choosing. Field "${key}" had "${rawValue}", using "${firstValid}"`
-  );
-  return firstValid;
+    if (!value.includes('|')) {
+        return value;
+    }
+    const parts = value.split('|').map((part) => part.trim());
+    const matchCount = parts.filter((part) => enumValues.includes(part)).length;
+    if (matchCount < 2) {
+        return value;
+    }
+    const firstValid = parts.find((part) => enumValues.includes(part));
+    if (!firstValid) {
+        return value;
+    }
+    console.warn(`⚠️  Model copied enum format instead of choosing. Field "${key}" had "${rawValue}", using "${firstValid}"`);
+    return firstValid;
 }
-
 function findEnumMatch(enumValues, value) {
-  return enumValues.find((entry) => entry.toUpperCase() === value);
+    return enumValues.find((entry) => entry.toUpperCase() === value);
 }
-
 function normalizeNestedValues(result, propSchema, key) {
-  // 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);
+    const value = result[key];
+    if (propSchema.type === 'object' && propSchema.properties && value) {
+        normalizeEnumValues(value, propSchema);
+    }
+    const itemSchema = propSchema.items;
+    if (propSchema.type === 'array' && itemSchema?.properties && Array.isArray(value)) {
+        for (const item of value) {
+            normalizeEnumValues(item, itemSchema);
+        }
     }
-  }
 }
-
 module.exports = {
-  normalizeEnumValues,
+    normalizeEnumValues,
 };

package/src/agent/schema-utils.ts

@@ -0,0 +1,148 @@
+/**
+ * Schema utilities for normalizing LLM output before validation.
+ *
+ * LLMs may return enum values that do not exactly match the schema. Normalize
+ * those values before validation without depending on a specific provider.
+ */
+
+interface EnumSchema {
+  type?: string;
+  enum?: string[];
+  properties?: Record<string, EnumSchema>;
+  items?: EnumSchema;
+}
+
+interface NormalizeEnumOptions {
+  result: Record<string, unknown>;
+  key: string;
+  propSchema: EnumSchema;
+}
+
+const ENUM_VARIATIONS: Readonly<Record<string, string>> = {
+  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',
+  EASY: 'TRIVIAL',
+  BASIC: 'SIMPLE',
+  MINOR: 'SIMPLE',
+  MODERATE: 'STANDARD',
+  MEDIUM: 'STANDARD',
+  NORMAL: 'STANDARD',
+  HARD: 'STANDARD',
+  COMPLEX: 'CRITICAL',
+  RISKY: 'CRITICAL',
+  HIGH_RISK: 'CRITICAL',
+  DANGEROUS: 'CRITICAL',
+};
+
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+/** Normalize enum values in parsed JSON, mutating and returning the same value. */
+function normalizeEnumValues(result: unknown, schema: EnumSchema | null | undefined): unknown {
+  if (!isObjectRecord(result) || !schema?.properties) {
+    return result;
+  }
+
+  for (const [key, propSchema] of Object.entries(schema.properties)) {
+    const matched = normalizeEnumValue({ result, key, propSchema });
+    if (matched) {
+      continue;
+    }
+
+    normalizeNestedValues(result, propSchema, key);
+  }
+
+  return result;
+}
+
+function normalizeEnumValue({ result, key, propSchema }: NormalizeEnumOptions): boolean {
+  const rawValue = result[key];
+  const enumValues = propSchema.enum;
+  if (!enumValues || typeof rawValue !== 'string') {
+    return false;
+  }
+
+  let value = rawValue.trim().toUpperCase();
+  value = normalizeEnumCopyValue(value, enumValues, key, rawValue);
+
+  const match = findEnumMatch(enumValues, value);
+  if (match) {
+    result[key] = match;
+    return true;
+  }
+
+  const variation = ENUM_VARIATIONS[value];
+  if (variation && enumValues.includes(variation)) {
+    result[key] = variation;
+  }
+
+  return false;
+}
+
+function normalizeEnumCopyValue(
+  value: string,
+  enumValues: string[],
+  key: string,
+  rawValue: string
+): string {
+  if (!value.includes('|')) {
+    return value;
+  }
+
+  const parts = value.split('|').map((part) => part.trim());
+  const matchCount = parts.filter((part) => enumValues.includes(part)).length;
+  if (matchCount < 2) {
+    return value;
+  }
+
+  const firstValid = parts.find((part) => enumValues.includes(part));
+  if (!firstValid) {
+    return value;
+  }
+
+  console.warn(
+    `⚠️  Model copied enum format instead of choosing. Field "${key}" had "${rawValue}", using "${firstValid}"`
+  );
+  return firstValid;
+}
+
+function findEnumMatch(enumValues: string[], value: string): string | undefined {
+  return enumValues.find((entry) => entry.toUpperCase() === value);
+}
+
+function normalizeNestedValues(
+  result: Record<string, unknown>,
+  propSchema: EnumSchema,
+  key: string
+): void {
+  const value = result[key];
+  if (propSchema.type === 'object' && propSchema.properties && value) {
+    normalizeEnumValues(value, propSchema);
+  }
+
+  const itemSchema = propSchema.items;
+  if (propSchema.type === 'array' && itemSchema?.properties && Array.isArray(value)) {
+    for (const item of value) {
+      normalizeEnumValues(item, itemSchema);
+    }
+  }
+}
+
+export = {
+  normalizeEnumValues,
+};

package/src/agent/structured-output-error.js

@@ -1,42 +1,43 @@
+"use strict";
 const STRUCTURED_OUTPUT_INVALID_CODE = 'STRUCTURED_OUTPUT_INVALID';
-
 function createStructuredOutputInvalidError(message, kind, validation = null, recovery = null) {
-  const error = new Error(message);
-  error.code = STRUCTURED_OUTPUT_INVALID_CODE;
-  error.details = {
-    kind,
-    validationError: validation?.error ?? null,
-    recoveryAttempts: recovery?.status === 'exhausted' ? recovery.attempts : 0,
-    recoveryError: recovery?.status === 'exhausted' ? recovery.lastError : null,
-  };
-  return error;
+    const properties = {
+        code: STRUCTURED_OUTPUT_INVALID_CODE,
+        details: {
+            kind,
+            validationError: validation?.error ?? null,
+            recoveryAttempts: recovery?.status === 'exhausted' ? recovery.attempts : 0,
+            recoveryError: recovery?.status === 'exhausted' ? recovery.lastError : null,
+        },
+    };
+    return Object.assign(new Error(message), properties);
 }
-
 function isStructuredOutputInvalidError(error) {
-  return error?.code === STRUCTURED_OUTPUT_INVALID_CODE;
+    if ((typeof error !== 'object' || error === null) && typeof error !== 'function') {
+        return false;
+    }
+    return 'code' in error && error.code === STRUCTURED_OUTPUT_INVALID_CODE;
 }
-
 function buildStructuredOutputClusterFailure(agent, error) {
-  return {
-    topic: 'CLUSTER_FAILED',
-    receiver: 'broadcast',
-    content: {
-      text: `Cluster failed: structured output is invalid for ${agent.id} - ${error.message}`,
-      data: {
-        reason: 'structured_output_invalid',
-        agentId: agent.id,
-        role: agent.role,
-        code: error.code,
-        details: error.details ?? null,
-        error: error.message,
-      },
-    },
-  };
+    return {
+        topic: 'CLUSTER_FAILED',
+        receiver: 'broadcast',
+        content: {
+            text: `Cluster failed: structured output is invalid for ${agent.id} - ${error.message}`,
+            data: {
+                reason: 'structured_output_invalid',
+                agentId: agent.id,
+                role: agent.role,
+                code: error.code,
+                details: error.details ?? null,
+                error: error.message,
+            },
+        },
+    };
 }
-
 module.exports = {
-  STRUCTURED_OUTPUT_INVALID_CODE,
-  createStructuredOutputInvalidError,
-  isStructuredOutputInvalidError,
-  buildStructuredOutputClusterFailure,
+    STRUCTURED_OUTPUT_INVALID_CODE,
+    createStructuredOutputInvalidError,
+    isStructuredOutputInvalidError,
+    buildStructuredOutputClusterFailure,
 };