@the-open-engine/zeroshot 6.38.1 → 6.39.0

package/src/agent/output-reformatter-errors.js

@@ -0,0 +1,83 @@
+"use strict";
+const INVOCATION_METADATA_FIELDS = [
+    'code',
+    'permanent',
+    'provider',
+    'capability',
+    'nestedExecutionCancellation',
+    'nestedExecutionLifecycle',
+    'retainTaskHandle',
+    'terminationExhausted',
+    'taskId',
+];
+function isProvidersBoundary(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        'getProvider' in value &&
+        typeof value.getProvider === 'function');
+}
+const rawProviders = require('../providers');
+if (!isProvidersBoundary(rawProviders)) {
+    throw new TypeError('providers module must expose getProvider');
+}
+const { getProvider } = rawProviders;
+function isRecoveryError(value) {
+    return value instanceof Error;
+}
+function invocationError(result) {
+    let error;
+    if (isRecoveryError(result?.error)) {
+        error = result.error;
+    }
+    else {
+        const message = result?.error ? String(result.error) : 'Structured-output recovery task failed';
+        error = new Error(message);
+    }
+    if (!result)
+        return error;
+    for (const field of INVOCATION_METADATA_FIELDS) {
+        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;
+}
+function recoveryErrorMessage(error, providerName) {
+    if (!isRecoveryError(error))
+        return null;
+    if (markImmediateRecoveryFailure(error, providerName))
+        throw error;
+    return error.message;
+}
+module.exports = {
+    invocationError,
+    markImmediateRecoveryFailure,
+    recoveryErrorMessage,
+};

package/src/agent/output-reformatter-errors.ts

@@ -0,0 +1,106 @@
+import type {
+  ProvidersBoundary,
+  RecoveryError,
+  ReformatInvocationResult,
+} from './output-reformatter-types';
+
+const INVOCATION_METADATA_FIELDS: readonly (
+  | 'code'
+  | 'permanent'
+  | 'provider'
+  | 'capability'
+  | 'nestedExecutionCancellation'
+  | 'nestedExecutionLifecycle'
+  | 'retainTaskHandle'
+  | 'terminationExhausted'
+  | 'taskId'
+)[] = [
+  'code',
+  'permanent',
+  'provider',
+  'capability',
+  'nestedExecutionCancellation',
+  'nestedExecutionLifecycle',
+  'retainTaskHandle',
+  'terminationExhausted',
+  'taskId',
+];
+
+function isProvidersBoundary(value: unknown): value is ProvidersBoundary {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    'getProvider' in value &&
+    typeof value.getProvider === 'function'
+  );
+}
+
+const rawProviders: unknown = require('../providers');
+if (!isProvidersBoundary(rawProviders)) {
+  throw new TypeError('providers module must expose getProvider');
+}
+const { getProvider } = rawProviders;
+
+function isRecoveryError(value: unknown): value is RecoveryError {
+  return value instanceof Error;
+}
+
+function invocationError(result: ReformatInvocationResult | null | undefined): RecoveryError {
+  let error: RecoveryError;
+  if (isRecoveryError(result?.error)) {
+    error = result.error;
+  } else {
+    const message = result?.error ? String(result.error) : 'Structured-output recovery task failed';
+    error = new Error(message);
+  }
+  if (!result) return error;
+
+  for (const field of INVOCATION_METADATA_FIELDS) {
+    if (result[field] !== undefined && error[field] === undefined) {
+      error[field] = result[field];
+    }
+  }
+  return error;
+}
+
+function isImmediateRecoveryFailure(error: RecoveryError, providerName: string): boolean {
+  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: RecoveryError, providerName: string): boolean {
+  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;
+}
+
+function recoveryErrorMessage(error: unknown, providerName: string): string | null {
+  if (!isRecoveryError(error)) return null;
+  if (markImmediateRecoveryFailure(error, providerName)) throw error;
+  return error.message;
+}
+
+export = {
+  invocationError,
+  markImmediateRecoveryFailure,
+  recoveryErrorMessage,
+};

package/src/agent/output-reformatter-types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/src/agent/output-reformatter-types.ts

@@ -0,0 +1,86 @@
+import type { ErrorObject, Schema } from 'ajv';
+
+export interface RuntimeProviderBoundary {
+  isRetryableError(error: Error): boolean;
+}
+
+export interface ProvidersBoundary {
+  getProvider(name: string): RuntimeProviderBoundary;
+}
+
+export interface SchemaUtilsBoundary {
+  normalizeEnumValues(result: unknown, schema: unknown): unknown;
+}
+
+export interface RecoveryError extends Error {
+  code?: unknown;
+  permanent?: unknown;
+  provider?: unknown;
+  capability?: unknown;
+  nestedExecutionCancellation?: unknown;
+  nestedExecutionLifecycle?: unknown;
+  retainTaskHandle?: unknown;
+  recoveryAbort?: unknown;
+  terminationExhausted?: unknown;
+  taskId?: unknown;
+}
+
+export interface ReformatInvocationResult {
+  success?: unknown;
+  output?: string;
+  error?: unknown;
+  code?: unknown;
+  permanent?: unknown;
+  provider?: unknown;
+  capability?: unknown;
+  nestedExecutionCancellation?: unknown;
+  nestedExecutionLifecycle?: unknown;
+  retainTaskHandle?: unknown;
+  terminationExhausted?: unknown;
+  taskId?: unknown;
+}
+
+export interface StructuredValidationResult {
+  valid: boolean;
+  value: unknown;
+  errors: ErrorObject[];
+  error: string | null;
+}
+
+export type StructuredOutputValidator = (candidate: unknown) => StructuredValidationResult;
+
+export type RunReformat = (
+  prompt: string
+) =>
+  | ReformatInvocationResult
+  | null
+  | undefined
+  | Promise<ReformatInvocationResult | null | undefined>;
+
+export interface ReformatOutputArguments {
+  rawOutput: string;
+  schema: Schema;
+  providerName: string;
+  maxAttempts?: number;
+  initialError?: string | null;
+  validateCandidate?: StructuredOutputValidator;
+  onAttempt?(attempt: number, lastError: string | null): unknown;
+  isCancelled?(): boolean;
+  runReformat?: RunReformat;
+}
+
+export interface RecoveryAttemptArguments {
+  prompt: string;
+  providerName: string;
+  validateCandidate: StructuredOutputValidator;
+  isCancelled(): boolean;
+  runReformat: RunReformat;
+}
+
+export type RecoveryAttemptOutcome =
+  | { status: 'recovered'; value: unknown }
+  | { status: 'retry'; error: string | null };
+
+export type ReformatOutcome =
+  | { status: 'recovered'; value: unknown; attempts: number }
+  | { status: 'exhausted'; attempts: number; lastError: string };

package/src/agent/output-reformatter.js

@@ -1,20 +1,38 @@
-const Ajv = require('ajv');
-const { getProvider } = require('../providers');
-const { normalizeEnumValues } = require('./schema-utils');
-
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const ajv_1 = __importDefault(require("ajv"));
+const outputReformatterErrors = require("./output-reformatter-errors");
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isSchemaUtilsBoundary(value) {
+    return isRecord(value) && typeof value.normalizeEnumValues === 'function';
+}
+function isOutputExtractionBoundary(value) {
+    return (isRecord(value) &&
+        typeof value.extractCliError === 'function' &&
+        typeof value.extractJsonFromOutput === 'function');
+}
+const { invocationError, markImmediateRecoveryFailure, recoveryErrorMessage } = outputReformatterErrors;
+const rawSchemaUtils = require('./schema-utils');
+if (!isSchemaUtilsBoundary(rawSchemaUtils)) {
+    throw new TypeError('schema-utils module must expose normalizeEnumValues');
+}
+const { normalizeEnumValues } = rawSchemaUtils;
 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;
+    const error = new Error('Output reformatting cancelled');
+    error.code = 'REFORMAT_CANCELLED';
+    error.recoveryAbort = true;
+    return error;
 }
-
 function buildReformatPrompt(rawOutput, schema, previousError = null) {
-  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.
+    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 the JSON-encoded source text into a JSON object matching the schema.
 
@@ -32,200 +50,137 @@ ${JSON.stringify(rawOutput)}
 - NO explanations
 - Start with { end with }
 - Match ALL required fields from schema`;
-
-  if (previousError) {
-    prompt += `
+    if (previousError) {
+        prompt += `
 
 ## PREVIOUS CANDIDATE FAILED
 ${previousError}
 Fix this issue in your response.`;
-  }
-
-  return prompt;
+    }
+    return prompt;
 }
-
 function formatValidationErrors(errors, limit = 5) {
-  return errors
-    .slice(0, limit)
-    .map((error) => `${error.instancePath || error.schemaPath || '#'} ${error.message}`)
-    .join('; ');
+    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',
+    const ajv = new ajv_1.default({
+        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;
+    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];
+    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;
     }
-  }
-  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;
+function loadOutputExtraction() {
+    const rawOutputExtraction = require('./output-extraction');
+    if (!isOutputExtractionBoundary(rawOutputExtraction)) {
+        throw new TypeError('output-extraction module must expose structured-output extractors');
+    }
+    return rawOutputExtraction;
 }
-
-async function reformatOutput({
-  rawOutput,
-  schema,
-  providerName,
-  maxAttempts = DEFAULT_MAX_ATTEMPTS,
-  initialError = null,
-  validateCandidate = createStructuredOutputValidator(schema),
-  onAttempt,
-  isCancelled = () => false,
-  runReformat,
-}) {
-  assertReformatRequest(rawOutput, maxAttempts);
-  if (typeof runReformat !== 'function') {
-    throw new Error('Output reformatting requires the active agent execution context');
-  }
-
-  const { extractCliError, extractJsonFromOutput } = require('./output-extraction');
-  let lastError = initialError;
-
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    if (isCancelled()) throw createCancellationError();
-    onAttempt?.(attempt, lastError);
-    const prompt = buildReformatPrompt(rawOutput, schema, lastError);
-
-    try {
-      const result = await runReformat(prompt);
-      if (isCancelled()) throw createCancellationError();
-      if (!result?.success) {
+async function recoverCandidate({ prompt, providerName, validateCandidate, isCancelled, runReformat, }) {
+    const result = await runReformat(prompt);
+    if (isCancelled())
+        throw createCancellationError();
+    if (!result?.success) {
         const error = invocationError(result);
-        if (markImmediateRecoveryFailure(error, providerName)) throw error;
-        lastError = error.message;
-        continue;
-      }
-      if (!result.output) {
-        lastError = 'Recovery task returned no output';
-        continue;
-      }
-      const terminalError = extractCliError(result.output, providerName);
-      if (terminalError) {
+        if (markImmediateRecoveryFailure(error, providerName))
+            throw error;
+        return { status: 'retry', error: error.message };
+    }
+    if (!result.output)
+        return { status: 'retry', error: 'Recovery task returned no output' };
+    const { extractCliError, extractJsonFromOutput } = loadOutputExtraction();
+    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 parsed = extractJsonFromOutput(result.output, providerName);
-      if (!parsed) {
-        lastError = 'Could not extract JSON from recovery output';
-        continue;
-      }
-      const validation = validateCandidate(parsed);
-      if (!validation.valid) {
-        lastError = validation.error;
-        continue;
-      }
-      return { status: 'recovered', value: validation.value, attempts: attempt };
-    } catch (error) {
-      if (isCancelled()) throw createCancellationError();
-      if (markImmediateRecoveryFailure(error, providerName)) throw error;
-      lastError = error.message;
+        if (markImmediateRecoveryFailure(error, providerName))
+            throw error;
+        return { status: 'retry', error: error.message };
     }
-  }
-
-  return {
-    status: 'exhausted',
-    attempts: maxAttempts,
-    lastError: lastError || 'Recovery attempts produced no schema-valid JSON object',
-  };
+    const parsed = extractJsonFromOutput(result.output, providerName);
+    if (!parsed)
+        return { status: 'retry', error: 'Could not extract JSON from recovery output' };
+    const validation = validateCandidate(parsed);
+    return validation.valid
+        ? { status: 'recovered', value: validation.value }
+        : { status: 'retry', error: validation.error };
+}
+async function reformatOutput({ rawOutput, schema, providerName, maxAttempts = DEFAULT_MAX_ATTEMPTS, initialError = null, validateCandidate = createStructuredOutputValidator(schema), onAttempt, isCancelled = () => false, runReformat, }) {
+    assertReformatRequest(rawOutput, maxAttempts);
+    if (typeof runReformat !== 'function') {
+        throw new Error('Output reformatting requires the active agent execution context');
+    }
+    let lastError = initialError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        if (isCancelled())
+            throw createCancellationError();
+        onAttempt?.(attempt, lastError);
+        const prompt = buildReformatPrompt(rawOutput, schema, lastError);
+        try {
+            const outcome = await recoverCandidate({
+                prompt,
+                providerName,
+                validateCandidate,
+                isCancelled,
+                runReformat,
+            });
+            if (outcome.status === 'recovered') {
+                return { status: 'recovered', value: outcome.value, attempts: attempt };
+            }
+            lastError = outcome.error;
+        }
+        catch (caught) {
+            if (isCancelled())
+                throw createCancellationError();
+            lastError = recoveryErrorMessage(caught, providerName);
+        }
+    }
+    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,
+    reformatOutput,
+    buildReformatPrompt,
+    createStructuredOutputValidator,
+    validateAgainstSchema,
+    DEFAULT_MAX_ATTEMPTS,
+    MAX_REFORMAT_INPUT_BYTES,
+    MAX_CONFIGURED_ATTEMPTS,
 };