/**
 * Ask User Question Tool
 *
 * 向用户提问以澄清需求或获取决策。
 * 参考 Claude Code 的 AskUserQuestion 实现。
 *
 * 特性：
 * - 支持 1-4 个问题
 * - 每个问题支持 2-4 个选项
 * - 支持单选/多选
 * - 系统自动添加 "Other" 选项供自由输入
 */

import type { ToolWithMetadata } from '../types.js';
import type { ToolResult } from '../../types/index.js';
import { loadDescription } from '../load_description.js';

/**
 * 选项定义
 */
export interface QuestionOption {
  /** 选项标签（1-5个词） */
  label: string;
  /** 选项说明 */
  description?: string;
}

/**
 * 问题定义
 */
export interface Question {
  /** 问题内容（应以问号结尾） */
  question: string;
  /** 简短标签（最多12字符） */
  header?: string;
  /** 选项列表（2-4个） */
  options?: QuestionOption[];
  /** 是否允许多选，默认 false */
  multiSelect?: boolean;
}

/**
 * 工具参数
 */
export interface AskUserQuestionParams {
  questions: Question[];
}

/**
 * 验证问题结构
 */
function validateQuestions(questions: Question[]): string | null {
  if (!Array.isArray(questions) || questions.length === 0) {
    return 'questions 必须是非空数组';
  }

  if (questions.length > 4) {
    return '最多只能包含 4 个问题';
  }

  for (let i = 0; i < questions.length; i++) {
    const q = questions[i];

    if (!q.question || typeof q.question !== 'string') {
      return `问题 ${i + 1}: question 是必需的字符串`;
    }

    if (q.header && q.header.length > 12) {
      return `问题 ${i + 1}: header 最多 12 个字符`;
    }

    if (q.options) {
      if (!Array.isArray(q.options)) {
        return `问题 ${i + 1}: options 必须是数组`;
      }

      if (q.options.length < 2 || q.options.length > 4) {
        return `问题 ${i + 1}: options 必须包含 2-4 个选项`;
      }

      for (let j = 0; j < q.options.length; j++) {
        const opt = q.options[j];
        if (!opt.label || typeof opt.label !== 'string') {
          return `问题 ${i + 1} 选项 ${j + 1}: label 是必需的字符串`;
        }
      }
    }
  }

  return null;
}

/**
 * 格式化问题为可读输出
 */
function formatQuestions(questions: Question[]): string {
  const output: string[] = [];

  for (let i = 0; i < questions.length; i++) {
    const q = questions[i];
    const questionNumber = questions.length > 1 ? `[${i + 1}/${questions.length}] ` : '';
    const header = q.header ? `【${q.header}】` : '';

    output.push(`${questionNumber}${header}${q.question}`);

    if (q.options && q.options.length > 0) {
      output.push('');
      const selectHint = q.multiSelect ? '(可多选)' : '(单选)';
      output.push(`选项 ${selectHint}:`);

      q.options.forEach((opt, idx) => {
        const optionKey = String.fromCharCode(65 + idx); // A, B, C, D
        const description = opt.description ? ` - ${opt.description}` : '';
        output.push(`  ${optionKey}. ${opt.label}${description}`);
      });

      // 自动添加 Other 选项
      const otherKey = String.fromCharCode(65 + q.options.length);
      output.push(`  ${otherKey}. Other - 自定义输入`);
    }

    if (i < questions.length - 1) {
      output.push('');
      output.push('---');
      output.push('');
    }
  }

  return output.join('\n');
}

/**
 * Ask User Question 工具
 */
export const askUserQuestionTool: ToolWithMetadata = {
  name: 'ask_user_question',
  description: loadDescription('ask_user_question'),

  metadata: {
    name: 'ask_user_question',
    category: 'agent',
    description: '向用户提问以澄清需求或获取决策',
    keywords: ['ask', 'question', 'clarify', 'decision', '提问', '澄清', '决策', '选择'],
    deferLoading: false, // 通用工具，始终可用
  },

  parameters: {
    questions: {
      type: 'array',
      description: '问题列表（1-4 个问题）',
      required: true,
    },
  },

  async execute(params: Record<string, unknown>): Promise<ToolResult> {
    const questions = params.questions as Question[];

    // 验证参数
    const validationError = validateQuestions(questions);
    if (validationError) {
      return {
        success: false,
        output: '',
        error: validationError,
      };
    }

    // 格式化输出
    const formattedOutput = formatQuestions(questions);

    return {
      success: true,
      output: formattedOutput,
      metadata: {
        type: 'ask_user_question',
        questionCount: questions.length,
        questions: questions.map((q, i) => ({
          index: i,
          header: q.header,
          optionCount: q.options?.length ?? 0,
          multiSelect: q.multiSelect ?? false,
        })),
        // 标记需要用户输入
        requiresUserInput: true,
      },
    };
  },
};
