import { UnrecoverableError } from './unrecoverable-error';
import type { FinishReason } from '@agforge/core';
/**
 * FinishReason 相关不可恢复错误。
 *
 * 当 LLM 返回的 `finishReason` 导致无法恢复的执行终止时抛出此错误。
 * 继承自 UnrecoverableError，确保 ErrorLimitInterceptor 能正确识别并跳过重试。
 *
 * ## 场景
 *
 * - `refusal`: 模型因安全策略或使用政策拒绝响应，重试无意义
 * - `length` / `content_filter`: 连续恢复尝试次数超限，无法继续
 *
 * ## 使用方式
 *
 * 上层应用可以通过 `instanceof FinishReasonError` 识别此错误类型，
 * 并根据 `finishReason` 属性判断具体场景：
 *
 * ```typescript
 * try {
 *   await agent.execute(task);
 * } catch (error) {
 *   if (error instanceof FinishReasonError) {
 *     if (error.finishReason === 'refusal') {
 *       console.log('模型拒绝了此请求，请修改后重试。');
 *     } else if (error.finishReason === 'length') {
 *       console.log(`输出超出 token 限制 ${error.attempts} 次，请简化任务。`);
 *     } else if (error.finishReason === 'content_filter') {
 *       console.log(`输出触发内容过滤 ${error.attempts} 次，请调整请求内容。`);
 *     }
 *   }
 * }
 * ```
 *
 * ## 设计决策
 *
 * - **不在拦截器层面定制提示词**：上层根据错误类型和 finishReason 自定义用户提示更合理
 * - **继承 UnrecoverableError**：确保 ErrorLimitInterceptor 能正确识别并跳过重试
 * - **统一错误类型**：通过 finishReason 属性区分场景，简化错误处理逻辑
 */
export declare class FinishReasonError extends UnrecoverableError {
    /** 导致错误的 finishReason */
    readonly finishReason: FinishReason;
    /** 恢复尝试次数（仅 length/content_filter 场景有效） */
    readonly attempts?: number;
    constructor(finishReason: FinishReason, attempts?: number);
}