@the-open-engine/zeroshot 6.16.0 → 6.18.0

package/src/agent/output-extraction.js

@@ -140,6 +140,28 @@ function extractFromTextEvents(output, providerName) {
   return null;
 }
 
+/**
+ * Assemble assistant text through the active provider parser. Recovery prompts
+ * use this instead of exposing raw event envelopes when model text exists.
+ *
+ * @param {string} output
+ * @param {string} providerName
+ * @returns {string|null}
+ */
+function extractModelTextFromOutput(output, providerName) {
+  if (!output || typeof output !== 'string') return null;
+  const normalized = output
+    .split('\n')
+    .map((line) => stripTimestamp(line))
+    .filter(Boolean)
+    .join('\n');
+  const text = parseProviderChunk(providerName, normalized)
+    .filter((event) => event.type === 'text' && typeof event.text === 'string')
+    .map((event) => event.text)
+    .join('');
+  return text.trim() ? text : null;
+}
+
 /**
  * Strategy 3: Extract JSON from markdown code block
  * Handles: ```json\n{...}\n```
@@ -280,13 +302,13 @@ function extractClaudeVertexModelError(output, { useVertex = false } = {}) {
  * Provider error formats:
  * - Claude: {type:"result", is_error:true, errors:["msg"]} or {type:"result", subtype:"error"}
  * - Codex:  {type:"turn.failed", error:{message:"msg"}}
- * - Gemini: {type:"result", success:false, error:"msg"}
+ * - Gemini: {type:"result", status:"error", error:{message:"msg"}} or {type:"error", severity:"error"}
  * - Opencode: {type:"session.error", error:{message:"msg"}}
  *
- * @param {string} output - Raw CLI output
+ * @param {string} providerName - Active provider whose terminal errors may be inspected
  * @returns {{error: string, provider: string}|null} Error info or null
  */
-function extractCliError(output) {
+function extractCliError(output, providerName = 'claude') {
   if (!output || typeof output !== 'string') return null;
 
   const lines = output.split('\n');
@@ -302,33 +324,35 @@ function extractCliError(output) {
       continue;
     }
 
-    // Claude: {type:"result", is_error:true, errors:[...]}
-    if (obj.type === 'result' && obj.is_error === true) {
+    if (providerName === 'claude' && obj.type === 'result' && obj.is_error === true) {
       const errorMsg = Array.isArray(obj.errors)
         ? obj.errors.join('; ')
         : obj.error || obj.result || 'Unknown CLI error';
       return { error: errorMsg, provider: 'claude' };
     }
 
-    // Claude: {type:"result", subtype:"error"}
-    if (obj.type === 'result' && obj.subtype === 'error') {
+    if (providerName === 'claude' && obj.type === 'result' && obj.subtype === 'error') {
       const errorMsg = obj.error || obj.result || 'CLI returned error';
       return { error: errorMsg, provider: 'claude' };
     }
 
-    // Codex: {type:"turn.failed", error:{message:"..."}}
-    if (obj.type === 'turn.failed') {
+    if (providerName === 'codex' && obj.type === 'turn.failed') {
       const errorMsg = obj.error?.message || obj.error || 'Turn failed';
       return { error: errorMsg, provider: 'codex' };
     }
 
-    // Gemini: {type:"result", success:false, error:"..."}
-    if (obj.type === 'result' && obj.success === false && obj.error) {
-      return { error: obj.error, provider: 'gemini' };
+    if (
+      providerName === 'gemini' &&
+      ((obj.type === 'result' && obj.status === 'error') ||
+        (obj.type === 'error' && obj.severity === 'error'))
+    ) {
+      return {
+        error: obj.error?.message || obj.message || 'Gemini CLI error',
+        provider: 'gemini',
+      };
     }
 
-    // Opencode: {type:"session.error", error:{...}}
-    if (obj.type === 'session.error') {
+    if (providerName === 'opencode' && (obj.type === 'session.error' || obj.type === 'error')) {
       const errorMsg =
         obj.error?.data?.message || obj.error?.message || obj.error?.name || 'Session error';
       return { error: errorMsg, provider: 'opencode' };
@@ -396,6 +420,7 @@ function extractJsonFromOutput(output, providerName = 'claude') {
 
 module.exports = {
   extractJsonFromOutput,
+  extractModelTextFromOutput,
   extractCliError,
   extractClaudeVertexModelError,
   extractFromResultWrapper,

package/src/agent/output-reformatter.js

@@ -1,49 +1,30 @@
-/**
- * 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.
- *
- * Opencode output can be reformatted through its CLI when direct JSON extraction fails.
- * Other providers remain on their own extraction paths and never depend on the opencode binary.
- */
+const Ajv = require('ajv');
+const { getProvider } = require('../providers');
+const { normalizeEnumValues } = require('./schema-utils');
 
 const DEFAULT_MAX_ATTEMPTS = 3;
-
+const MAX_REFORMAT_INPUT_BYTES = 65_536;
+const MAX_CONFIGURED_ATTEMPTS = 10;
 
 function createCancellationError() {
   const error = new Error('Output reformatting cancelled');
   error.code = 'REFORMAT_CANCELLED';
+  error.recoveryAbort = true;
   return error;
 }
 
-
-/**
- * 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 = `CRITICAL: Do NOT use any tools. Do NOT read, write, or edit any files. Do NOT explore the codebase. This is a pure text-to-JSON transformation — respond with JSON only.
 
-Convert this text into a JSON object matching the schema.
+Convert the JSON-encoded source text into a JSON object matching the schema.
 
 ## SCHEMA
 \`\`\`json
-${schemaStr}
+${JSON.stringify(schema, null, 2)}
 \`\`\`
 
-## TEXT TO CONVERT
-\`\`\`
-${truncatedOutput}
-\`\`\`
+## JSON-ENCODED SOURCE TEXT
+${JSON.stringify(rawOutput)}
 
 ## RULES
 - Output ONLY the JSON object
@@ -55,134 +36,196 @@ ${truncatedOutput}
   if (previousError) {
     prompt += `
 
-## PREVIOUS ATTEMPT FAILED
-Error: ${previousError}
+## PREVIOUS CANDIDATE FAILED
+${previousError}
 Fix this issue in your response.`;
   }
 
   return prompt;
 }
 
-/**
- * This fallback is intentionally scoped to opencode agents. It participates in agent
- * cancellation so retries cannot outlive cluster shutdown.
- *
- * @param {Object} options
- * @param {string} options.rawOutput - The non-JSON output to reformat
- * @param {Object} options.schema - Target JSON schema
- * @param {string} options.providerName - Active provider name
- * @param {number} [options.maxAttempts=3] - Maximum reformatting attempts
- * @param {Function} [options.onAttempt] - Callback for each attempt (attempt, error)
- * @param {Function} [options.isCancelled] - Returns true after agent cancellation
- * @param {Function} options.runReformat - Runs the prompt in the active agent execution context
- * @returns {Promise<Object>} The reformatted JSON object
- * @throws {Error} If the provider is unsupported, cancellation occurs, or attempts fail
- */
+function formatValidationErrors(errors, limit = 5) {
+  return errors
+    .slice(0, limit)
+    .map((error) => `${error.instancePath || error.schemaPath || '#'} ${error.message}`)
+    .join('; ');
+}
+
+function createStructuredOutputValidator(schema) {
+  const ajv = new Ajv({
+    allErrors: true,
+    strict: false,
+    coerceTypes: false,
+    useDefaults: true,
+    removeAdditional: true,
+  });
+  const validate = ajv.compile(schema);
+
+  return (candidate) => {
+    normalizeEnumValues(candidate, schema);
+    const valid = validate(candidate);
+    const errors = (validate.errors || []).map((error) => ({ ...error }));
+    return {
+      valid,
+      value: candidate,
+      errors,
+      error: valid ? null : formatValidationErrors(errors) || 'Schema validation failed',
+    };
+  };
+}
+
+function validateAgainstSchema(parsed, schema) {
+  return createStructuredOutputValidator(schema)(parsed).error;
+}
+
+function assertReformatRequest(rawOutput, maxAttempts) {
+  if (!Number.isInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > MAX_CONFIGURED_ATTEMPTS) {
+    const error = new RangeError(
+      `Output reformatting maxAttempts must be an integer from 1 through ${MAX_CONFIGURED_ATTEMPTS}`
+    );
+    error.code = 'REFORMAT_INVALID_ATTEMPT_LIMIT';
+    error.permanent = true;
+    throw error;
+  }
+  if (Buffer.byteLength(rawOutput || '', 'utf8') > MAX_REFORMAT_INPUT_BYTES) {
+    const error = new Error(
+      `Output reformatting input exceeds ${MAX_REFORMAT_INPUT_BYTES} UTF-8 bytes`
+    );
+    error.code = 'REFORMAT_INPUT_TOO_LARGE';
+    error.permanent = true;
+    throw error;
+  }
+}
+
+function invocationError(result) {
+  const error =
+    result?.error instanceof Error
+      ? result.error
+      : new Error(result?.error || 'Structured-output recovery task failed');
+  for (const field of [
+    'code',
+    'permanent',
+    'provider',
+    'capability',
+    'nestedExecutionCancellation',
+    'nestedExecutionLifecycle',
+    'retainTaskHandle',
+    'terminationExhausted',
+    'taskId',
+  ]) {
+    if (result?.[field] !== undefined && error[field] === undefined) {
+      error[field] = result[field];
+    }
+  }
+  return error;
+}
+
+function isImmediateRecoveryFailure(error, providerName) {
+  if (
+    error?.code === 'REFORMAT_CANCELLED' ||
+    error?.code === 'AGENT_TASK_TIMEOUT' ||
+    error?.nestedExecutionCancellation === true ||
+    error?.nestedExecutionLifecycle === true ||
+    error?.retainTaskHandle === true ||
+    error?.permanent === true ||
+    error?.terminationExhausted === true
+  ) {
+    return true;
+  }
+  return !getProvider(providerName).isRetryableError(error);
+}
+
+function markImmediateRecoveryFailure(error, providerName) {
+  if (!isImmediateRecoveryFailure(error, providerName)) return false;
+  error.recoveryAbort = true;
+  const operationalControl =
+    error.code === 'REFORMAT_CANCELLED' ||
+    error.code === 'AGENT_TASK_TIMEOUT' ||
+    error.nestedExecutionCancellation === true ||
+    error.nestedExecutionLifecycle === true ||
+    error.retainTaskHandle === true ||
+    error.terminationExhausted === true;
+  if (!operationalControl && error.permanent !== true) error.permanent = true;
+  return true;
+}
+
 async function reformatOutput({
   rawOutput,
   schema,
   providerName,
   maxAttempts = DEFAULT_MAX_ATTEMPTS,
+  initialError = null,
+  validateCandidate = createStructuredOutputValidator(schema),
   onAttempt,
   isCancelled = () => false,
   runReformat,
 }) {
-  if (providerName !== 'opencode') {
-    throw new Error(
-      `Output reformatting not available for provider "${providerName}". ` +
-        `Agent output must be valid JSON. Raw output (last 200 chars): ${(rawOutput || '').slice(-200)}`
-    );
-  }
+  assertReformatRequest(rawOutput, maxAttempts);
   if (typeof runReformat !== 'function') {
     throw new Error('Output reformatting requires the active agent execution context');
   }
 
-
-  const { extractJsonFromOutput } = require('./output-extraction');
-  let lastError = null;
+  const { extractCliError, extractJsonFromOutput } = require('./output-extraction');
+  let lastError = initialError;
 
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     if (isCancelled()) throw createCancellationError();
-    if (onAttempt) {
-      onAttempt(attempt, lastError);
-    }
-
+    onAttempt?.(attempt, lastError);
     const prompt = buildReformatPrompt(rawOutput, schema, lastError);
 
     try {
       const result = await runReformat(prompt);
       if (isCancelled()) throw createCancellationError();
       if (!result?.success) {
-        lastError = result?.error || 'reformat task failed';
+        const error = invocationError(result);
+        if (markImmediateRecoveryFailure(error, providerName)) throw error;
+        lastError = error.message;
         continue;
       }
-      const output = result.output;
-      if (!output) {
-        lastError = 'reformat task returned no output';
+      if (!result.output) {
+        lastError = 'Recovery task returned no output';
         continue;
       }
-
-      const parsed = extractJsonFromOutput(output, 'opencode');
-      if (!parsed) {
-        lastError = 'Could not extract JSON from reformatted output';
+      const terminalError = extractCliError(result.output, providerName);
+      if (terminalError) {
+        const error = new Error(terminalError.error);
+        error.provider = terminalError.provider;
+        if (markImmediateRecoveryFailure(error, providerName)) throw error;
+        lastError = error.message;
         continue;
       }
 
-      const validationError = validateAgainstSchema(parsed, schema);
-      if (validationError) {
-        lastError = validationError;
+      const parsed = extractJsonFromOutput(result.output, providerName);
+      if (!parsed) {
+        lastError = 'Could not extract JSON from recovery output';
         continue;
       }
-
-      return parsed;
-    } catch (err) {
-      if (
-        err.code === 'REFORMAT_CANCELLED' ||
-        err.code === 'AGENT_TASK_TIMEOUT' ||
-        err.nestedExecutionLifecycle === true ||
-        err.retainTaskHandle === true ||
-        err.permanent === true ||
-        err.terminationExhausted === true
-      ) {
-        throw err;
+      const validation = validateCandidate(parsed);
+      if (!validation.valid) {
+        lastError = validation.error;
+        continue;
       }
-      lastError = err.message;
+      return { status: 'recovered', value: validation.value, attempts: attempt };
+    } catch (error) {
+      if (isCancelled()) throw createCancellationError();
+      if (markImmediateRecoveryFailure(error, providerName)) throw error;
+      lastError = error.message;
     }
   }
 
-  throw new Error(
-    `Failed to reformat output after ${maxAttempts} attempts (provider "${providerName}"). ` +
-      `Last error: ${lastError}. Raw output (last 200 chars): ${(rawOutput || '').slice(-200)}`
-  );
-}
-
-/**
- * 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;
+  return {
+    status: 'exhausted',
+    attempts: maxAttempts,
+    lastError: lastError || 'Recovery attempts produced no schema-valid JSON object',
+  };
 }
 
 module.exports = {
   reformatOutput,
   buildReformatPrompt,
+  createStructuredOutputValidator,
   validateAgainstSchema,
   DEFAULT_MAX_ATTEMPTS,
+  MAX_REFORMAT_INPUT_BYTES,
+  MAX_CONFIGURED_ATTEMPTS,
 };

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

@@ -1,4 +1,5 @@
 import { getString, isRecord, stringifyJson, tryParseJson } from '../json';
+import { UnsupportedProviderCapabilityError } from '../errors';
 import { contractError } from '../contract-errors';
 import {
   type BuildProviderCommandOptions,
@@ -9,7 +10,7 @@ import {
   type LevelOverrides,
   type ModelCatalogEntry,
   type ModelLevel,
-  type ProviderAdapter,
+  type StructuredOutputRecoveryAdapter,
   type ResolvedModelSpec,
   type WarningMetadata,
 } from '../types';
@@ -72,6 +73,9 @@ function detectCliFeatures(helpText?: string | null): ClaudeCliFeatures {
     supportsSettings: !unknown && /--settings/.test(help),
     supportsMcpConfig: !unknown && /--mcp-config/.test(help),
     supportsResume: unknown ? true : /--resume/.test(help),
+    supportsTools: !unknown && /--tools\b/.test(help),
+    supportsStrictMcpConfig: !unknown && /--strict-mcp-config\b/.test(help),
+    supportsNoSessionPersistence: !unknown && /--no-session-persistence\b/.test(help),
     unknown,
   };
 }
@@ -252,6 +256,38 @@ function buildCommand(context: string, options: BuildProviderCommandOptions = {}
   });
 }
 
+function assertStructuredOutputRecoveryFeatures(options: BuildProviderCommandOptions): void {
+  const features = optionFeatures(options);
+  const missing = [
+    ['--tools', features.supportsTools],
+    ['--strict-mcp-config', features.supportsStrictMcpConfig],
+    ['--no-session-persistence', features.supportsNoSessionPersistence],
+  ].filter(([, supported]) => supported !== true);
+  if (missing.length === 0) return;
+  throw new UnsupportedProviderCapabilityError(
+    'claude',
+    'structuredOutputRecovery',
+    `Claude structured-output recovery requires CLI evidence for ${missing.map(([flag]) => flag).join(', ')}. Upgrade Claude Code before retrying.`
+  );
+}
+
+function buildStructuredOutputRecoveryCommand(
+  context: string,
+  options: BuildProviderCommandOptions = {}
+): CommandSpec {
+  assertStructuredOutputRecoveryFeatures(options);
+  const recoveryOptions = { ...options };
+  delete recoveryOptions.resumeSessionId;
+  delete recoveryOptions.continueSession;
+  delete recoveryOptions.mcpConfig;
+  const spec = buildCommand(context, { ...recoveryOptions, autoApprove: false });
+  const args = [...spec.args];
+  const prompt = args.pop();
+  if (prompt === undefined) throw new Error('Claude recovery command is missing its prompt');
+  args.push('--tools', '', '--strict-mcp-config', '--no-session-persistence', prompt);
+  return { ...spec, args };
+}
+
 function resolveModelSpec(level: ModelLevel, overrides?: LevelOverrides): ResolvedModelSpec {
   return resolveModelSpecWithConfig({
     mapping: LEVEL_MAPPING,
@@ -274,7 +310,7 @@ function classifyError(error: unknown): ErrorClassification {
   );
 }
 
-export const claudeAdapter: ProviderAdapter = {
+export const claudeAdapter: StructuredOutputRecoveryAdapter = {
   id: 'claude',
   displayName: 'Claude',
   binary: 'claude',
@@ -287,6 +323,7 @@ export const claudeAdapter: ProviderAdapter = {
   defaultMinLevel: 'level1',
   detectCliFeatures,
   buildCommand,
+  buildStructuredOutputRecoveryCommand,
   extractSessionId,
   parseEvent: parseClaudeEvent,
   createParserState: () => createParserState('claude'),

package/src/agent-cli-provider/adapters/codex.ts

@@ -10,7 +10,7 @@ import {
   type LevelOverrides,
   type ModelCatalogEntry,
   type ModelLevel,
-  type ProviderAdapter,
+  type StructuredOutputRecoveryAdapter,
   type ResolvedModelSpec,
   type WarningMetadata,
 } from '../types';
@@ -67,6 +67,11 @@ function detectCliFeatures(
     supportsResume: supports(help, /\bresume\b/),
     supportsWebSearch:
       !unknown && supportsConfigOverride && isCliVersionAtLeast(versionText, '0.146.0'),
+    supportsSandbox: !unknown && /--sandbox\b/.test(help),
+    supportsEphemeral: !unknown && /--ephemeral\b/.test(help),
+    supportsIgnoreUserConfig: !unknown && /--ignore-user-config\b/.test(help),
+    supportsIgnoreRules: !unknown && /--ignore-rules\b/.test(help),
+    supportsStrictConfig: !unknown && /--strict-config\b/.test(help),
     unknown,
   };
 }
@@ -245,6 +250,54 @@ function buildCommand(context: string, options: BuildProviderCommandOptions = {}
   });
 }
 
+function assertStructuredOutputRecoveryFeatures(options: BuildProviderCommandOptions): void {
+  const features = optionFeatures(options);
+  const missing = [
+    ['--sandbox', features.supportsSandbox],
+    ['--ephemeral', features.supportsEphemeral],
+    ['--ignore-user-config', features.supportsIgnoreUserConfig],
+    ['--ignore-rules', features.supportsIgnoreRules],
+    ['--strict-config', features.supportsStrictConfig],
+    ['--config', features.supportsConfigOverride],
+  ].filter(([, supported]) => supported !== true);
+  if (missing.length === 0) return;
+  throw new UnsupportedProviderCapabilityError(
+    'codex',
+    'structuredOutputRecovery',
+    `Codex structured-output recovery requires CLI evidence for ${missing.map(([flag]) => flag).join(', ')}. Upgrade @openai/codex before retrying.`
+  );
+}
+
+function buildStructuredOutputRecoveryCommand(
+  context: string,
+  options: BuildProviderCommandOptions = {}
+): CommandSpec {
+  assertStructuredOutputRecoveryFeatures(options);
+  const recoveryOptions = { ...options };
+  delete recoveryOptions.resumeSessionId;
+  delete recoveryOptions.continueSession;
+  const spec = buildCommand(context, {
+    ...recoveryOptions,
+    autoApprove: false,
+    webSearch: false,
+  });
+  const args = [...spec.args];
+  const prompt = args.pop();
+  if (prompt === undefined) throw new Error('Codex recovery command is missing its prompt');
+  args.push(
+    '--sandbox',
+    'read-only',
+    '--ephemeral',
+    '--ignore-user-config',
+    '--ignore-rules',
+    '--strict-config',
+    '--config',
+    'web_search="disabled"',
+    prompt
+  );
+  return { ...spec, args };
+}
+
 function resolveModelSpec(level: ModelLevel, overrides?: LevelOverrides): ResolvedModelSpec {
   return resolveModelSpecWithConfig({
     mapping: LEVEL_MAPPING,
@@ -267,7 +320,7 @@ function classifyError(error: unknown): ErrorClassification {
   );
 }
 
-export const codexAdapter: ProviderAdapter = {
+export const codexAdapter: StructuredOutputRecoveryAdapter = {
   id: 'codex',
   displayName: 'Codex',
   binary: 'codex',
@@ -280,6 +333,7 @@ export const codexAdapter: ProviderAdapter = {
   defaultMinLevel: 'level1',
   detectCliFeatures,
   buildCommand,
+  buildStructuredOutputRecoveryCommand,
   extractSessionId,
   parseEvent: parseCodexEvent,
   createParserState: () => createParserState('codex'),