@the-open-engine/zeroshot 5.4.0

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

@@ -0,0 +1,82 @@
+/**
+ * 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
+ */
+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
+  );
+}
+
+/**
+ * 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
+ */
+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;
+}
+
+/**
+ * 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
+ */
+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);
+}
+
+module.exports = {
+  calculateRateLimitDelay,
+  isRateLimitError,
+  parseRetryAfter,
+};

package/src/agent/schema-utils.js

@@ -0,0 +1,146 @@
+/**
+ * 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.
+ */
+
+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',
+};
+
+/**
+ * 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)) {
+    const matched = normalizeEnumValue({
+      result,
+      key,
+      propSchema,
+    });
+    if (matched) {
+      continue;
+    }
+
+    // Recursively handle nested objects
+    normalizeNestedValues(result, propSchema, key);
+  }
+
+  return result;
+}
+
+function normalizeEnumValue({ result, key, propSchema }) {
+  if (!propSchema.enum || typeof result[key] !== 'string') {
+    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;
+}
+
+function findEnumMatch(enumValues, 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);
+    }
+  }
+}
+
+module.exports = {
+  normalizeEnumValues,
+};

package/src/agent/validation-platform.js

@@ -0,0 +1,35 @@
+const PLATFORM_MISMATCH_REGEX =
+  /EBADPLATFORM|Unsupported platform|darwin-arm64|linux-x64|@esbuild\/linux-x64/i;
+
+function isPlatformMismatchReason(reason) {
+  if (!reason) return false;
+  return PLATFORM_MISMATCH_REGEX.test(String(reason));
+}
+
+function findPlatformMismatchReason(result = {}) {
+  const criteriaResults = result.criteriaResults;
+  if (Array.isArray(criteriaResults)) {
+    for (const criteria of criteriaResults) {
+      if (criteria?.status !== 'CANNOT_VALIDATE') continue;
+      if (isPlatformMismatchReason(criteria.reason)) {
+        return String(criteria.reason);
+      }
+    }
+  }
+
+  const errors = result.errors;
+  if (Array.isArray(errors)) {
+    for (const error of errors) {
+      if (isPlatformMismatchReason(error)) {
+        return String(error);
+      }
+    }
+  }
+
+  return null;
+}
+
+module.exports = {
+  isPlatformMismatchReason,
+  findPlatformMismatchReason,
+};

package/src/agent-cli-provider/adapters/claude-parser.ts

@@ -0,0 +1,133 @@
+import {
+  getArray,
+  getNumber,
+  getOptionalString,
+  getRecord,
+  getString,
+  isRecord,
+  stringifyJson,
+  tryParseJson,
+} from '../json';
+import type { OutputEvent, ProviderParseResult, ResultEvent } from '../types';
+
+function cacheReadInputTokens(usage: Record<string, unknown>): number {
+  return (
+    getNumber(usage, 'cache_read_input_tokens') ?? getNumber(usage, 'cached_input_tokens') ?? 0
+  );
+}
+
+function parseResultEvent(event: Record<string, unknown>): OutputEvent {
+  const usage = getRecord(event, 'usage') ?? {};
+  const result: ResultEvent = {
+    type: 'result',
+    success: getString(event, 'subtype') === 'success',
+    result: event.result,
+    error: event.is_error ? event.result : null,
+    cost: event.total_cost_usd,
+    duration: event.duration_ms,
+    inputTokens: getNumber(usage, 'input_tokens') ?? 0,
+    outputTokens: getNumber(usage, 'output_tokens') ?? 0,
+    cacheReadInputTokens: cacheReadInputTokens(usage),
+    cacheCreationInputTokens: getNumber(usage, 'cache_creation_input_tokens') ?? 0,
+    modelUsage: event.modelUsage ?? null,
+  };
+  return result;
+}
+
+function parseStreamEvent(inner: Record<string, unknown>): OutputEvent | null {
+  if (getString(inner, 'type') !== 'content_block_delta') return null;
+  const delta = getRecord(inner, 'delta');
+  if (delta === null) return null;
+
+  if (getString(delta, 'type') === 'text_delta') {
+    const text = getString(delta, 'text');
+    return text ? { type: 'text', text } : null;
+  }
+
+  if (getString(delta, 'type') === 'thinking_delta') {
+    const text = getString(delta, 'thinking');
+    return text ? { type: 'thinking', text } : null;
+  }
+
+  return null;
+}
+
+function parseAssistantBlock(block: Record<string, unknown>): OutputEvent | null {
+  const blockType = getString(block, 'type');
+  if (blockType === 'text') {
+    const text = getString(block, 'text');
+    return text ? { type: 'text', text } : null;
+  }
+  if (blockType === 'tool_use') {
+    return {
+      type: 'tool_call',
+      toolName: getOptionalString(block, 'name'),
+      toolId: getOptionalString(block, 'id'),
+      input: block.input,
+    };
+  }
+  if (blockType === 'thinking') {
+    const text = getString(block, 'thinking');
+    return text ? { type: 'thinking', text } : null;
+  }
+  return null;
+}
+
+function parseEventList(events: readonly OutputEvent[]): ProviderParseResult {
+  if (events.length === 1) return events[0] ?? null;
+  if (events.length > 1) return events;
+  return null;
+}
+
+function parseAssistantMessage(message: Record<string, unknown>): ProviderParseResult {
+  const results: OutputEvent[] = [];
+  for (const blockValue of getArray(message, 'content')) {
+    if (!isRecord(blockValue)) continue;
+    const event = parseAssistantBlock(blockValue);
+    if (event !== null) results.push(event);
+  }
+  return parseEventList(results);
+}
+
+function parseUserBlock(block: Record<string, unknown>): OutputEvent | null {
+  if (getString(block, 'type') !== 'tool_result') return null;
+  const content = block.content;
+  return {
+    type: 'tool_result',
+    toolId: getOptionalString(block, 'tool_use_id'),
+    content:
+      typeof content === 'string' || content === undefined ? content : stringifyJson(content),
+    isError: block.is_error || false,
+  };
+}
+
+function parseUserMessage(message: Record<string, unknown>): ProviderParseResult {
+  const results: OutputEvent[] = [];
+  for (const blockValue of getArray(message, 'content')) {
+    if (!isRecord(blockValue)) continue;
+    const event = parseUserBlock(blockValue);
+    if (event !== null) results.push(event);
+  }
+  return parseEventList(results);
+}
+
+export function parseClaudeEvent(line: string): ProviderParseResult {
+  const parsed = tryParseJson(line.trim());
+  if (!isRecord(parsed)) return null;
+
+  const eventType = getString(parsed, 'type');
+  if (eventType === 'stream_event') {
+    const inner = getRecord(parsed, 'event');
+    return inner === null ? null : parseStreamEvent(inner);
+  }
+  if (eventType === 'assistant') {
+    const message = getRecord(parsed, 'message');
+    return message === null ? null : parseAssistantMessage(message);
+  }
+  if (eventType === 'user') {
+    const message = getRecord(parsed, 'message');
+    return message === null ? null : parseUserMessage(message);
+  }
+  if (eventType === 'result') return parseResultEvent(parsed);
+  return null;
+}

package/src/agent-cli-provider/adapters/claude-recovery.ts

@@ -0,0 +1,203 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { getString, isRecord, tryParseJson } from '../json';
+
+export const STREAMING_MODE_ERROR = 'only prompt commands are supported in streaming mode';
+export const NO_MESSAGES_RETURNED = 'No messages returned';
+
+export interface StreamingModeError {
+  readonly sessionId: string;
+  readonly line: string;
+}
+
+export interface StructuredOutputRecovery {
+  readonly payload: Record<string, unknown>;
+  readonly sourcePath: string;
+}
+
+export function detectProviderStreamingModeError(
+  provider: string,
+  line: unknown
+): StreamingModeError | null {
+  if (!isClaudeProvider(provider)) return null;
+  return detectClaudeStreamingModeError(line);
+}
+
+export function detectProviderFatalError(provider: string, line: unknown): string | null {
+  if (!isClaudeProvider(provider)) return null;
+  return detectClaudeFatalError(line);
+}
+
+export function recoverProviderStructuredOutput(
+  provider: string,
+  sessionId: string
+): StructuredOutputRecovery | null {
+  if (!isClaudeProvider(provider)) return null;
+  return recoverClaudeStructuredOutput(sessionId);
+}
+
+export function supportsProviderStructuredOutputRecovery(provider: string): boolean {
+  return isClaudeProvider(provider);
+}
+
+function isClaudeProvider(provider: string): boolean {
+  const normalized = provider.toLowerCase();
+  return normalized === 'claude' || normalized === 'anthropic';
+}
+
+function detectClaudeStreamingModeError(line: unknown): StreamingModeError | null {
+  const trimmed = typeof line === 'string' ? line.trim() : '';
+  if (!trimmed.startsWith('{')) return null;
+
+  const parsed = tryParseJson(trimmed);
+  if (
+    isRecord(parsed) &&
+    parsed.type === 'result' &&
+    parsed.is_error === true &&
+    Array.isArray(parsed.errors) &&
+    parsed.errors.includes(STREAMING_MODE_ERROR) &&
+    typeof parsed.session_id === 'string'
+  ) {
+    return {
+      sessionId: parsed.session_id,
+      line: trimmed,
+    };
+  }
+
+  return null;
+}
+
+function detectClaudeFatalError(line: unknown): string | null {
+  if (typeof line !== 'string') return null;
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+
+  if (trimmed.startsWith('{') && tryParseJson(trimmed) !== null) {
+    return null;
+  }
+
+  if (trimmed.toLowerCase().includes(NO_MESSAGES_RETURNED.toLowerCase())) {
+    return `Claude CLI error: ${NO_MESSAGES_RETURNED}`;
+  }
+
+  return null;
+}
+
+function findSessionJsonlPath(sessionId: string): string | null {
+  const claudeDir = process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
+  const projectsDir = join(claudeDir, 'projects');
+  if (!existsSync(projectsDir)) return null;
+
+  const target = `${sessionId}.jsonl`;
+  const queue: string[] = [projectsDir];
+
+  while (queue.length > 0) {
+    const dir = queue.pop();
+    if (dir === undefined) continue;
+
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name === target) {
+        return join(dir, entry.name);
+      }
+      if (entry.isDirectory()) {
+        queue.push(join(dir, entry.name));
+      }
+    }
+  }
+
+  return null;
+}
+
+function recoverClaudeStructuredOutput(sessionId: string): StructuredOutputRecovery | null {
+  const jsonlPath = findSessionJsonlPath(sessionId);
+  if (jsonlPath === null) return null;
+
+  const fileContents = readJsonlFile(jsonlPath);
+  if (fileContents === null) return null;
+
+  const { structuredOutput, usage } = findStructuredOutput(fileContents);
+  if (structuredOutput === null) return null;
+
+  return {
+    payload: buildStructuredOutputPayload(sessionId, structuredOutput, usage),
+    sourcePath: jsonlPath,
+  };
+}
+
+function readJsonlFile(jsonlPath: string): string | null {
+  try {
+    return readFileSync(jsonlPath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function findStructuredOutput(fileContents: string): {
+  readonly structuredOutput: Record<string, unknown> | null;
+  readonly usage: Record<string, unknown> | null;
+} {
+  const lines = fileContents.split('\n');
+  let structuredOutput: Record<string, unknown> | null = null;
+  let usage: Record<string, unknown> | null = null;
+
+  for (const line of lines) {
+    const entry = tryParseJson(line);
+    if (!isRecord(entry)) continue;
+
+    const extracted = extractStructuredOutputFromEntry(entry);
+    if (extracted !== null) {
+      structuredOutput = extracted.structuredOutput;
+      usage = extracted.usage;
+    }
+  }
+
+  return { structuredOutput, usage };
+}
+
+function extractStructuredOutputFromEntry(entry: Record<string, unknown>): {
+  readonly structuredOutput: Record<string, unknown>;
+  readonly usage: Record<string, unknown> | null;
+} | null {
+  const message = entry.message;
+  if (!isRecord(message) || !Array.isArray(message.content)) return null;
+
+  let structuredOutput: Record<string, unknown> | null = null;
+  let usage: Record<string, unknown> | null = null;
+  for (const block of message.content) {
+    if (
+      isRecord(block) &&
+      getString(block, 'type') === 'tool_use' &&
+      getString(block, 'name') === 'StructuredOutput' &&
+      isRecord(block.input)
+    ) {
+      structuredOutput = block.input;
+      usage = isRecord(message.usage) ? message.usage : null;
+    }
+  }
+
+  if (structuredOutput === null) return null;
+  return { structuredOutput, usage };
+}
+
+function buildStructuredOutputPayload(
+  sessionId: string,
+  structuredOutput: Record<string, unknown>,
+  usage: Record<string, unknown> | null
+): Record<string, unknown> {
+  return {
+    type: 'result',
+    subtype: 'success',
+    is_error: false,
+    structured_output: structuredOutput,
+    session_id: sessionId,
+    ...(usage === null ? {} : { usage }),
+  };
+}