from __future__ import annotations

from collections.abc import Mapping

from ..agent_tool_core import AgentTool, ToolHandler
from ._builder import resolve_handler


def build_execution_tools(handlers: Mapping[str, ToolHandler]) -> list[AgentTool]:
    """构建本地命令、Python 执行与短等待工具声明。"""

    return [
        AgentTool(
            name='python_exec',
            description=(
                '优先用本工具执行小型 Python 代码或项目内 Python 脚本，用于结构化文件分析、'
                'JSON/JSONL 处理、批量校验、数据抽样和快速计算。默认使用当前用户独立 Python venv；'
                '不要用 bash 运行 python/python3/.venv/bin/python。不要用本工具安装依赖。'
                '缺包时应向用户确认后再处理依赖。一次性分析优先传 code；项目或 skill 内已有脚本优先传 script_path，'
                '不要在 code 里用 subprocess 二次调用 Python 脚本。如需写临时文件，'
                '必须写入环境变量 PYTHON_EXEC_SCRATCHPAD 指向的会话隔离目录，'
                '不要在项目根目录创建临时 .py 脚本。'
            ),
            parameters={
                'type': 'object',
                'properties': {
                    'code': {
                        'type': 'string',
                        'description': '要通过 python -c 执行的 Python 代码。code 和 script_path 必须二选一；一次性分析优先使用 code。',
                    },
                    'script_path': {
                        'type': 'string',
                        'description': '工作区内已有、需要长期复用的 Python 脚本路径。code 和 script_path 必须二选一；不要为一次性分析在项目根目录新建脚本。',
                    },
                    'args': {
                        'type': 'array',
                        'items': {'type': 'string'},
                        'description': '传给脚本的命令行参数。仅在 script_path 模式下使用。',
                    },
                    'stdin': {
                        'type': 'string',
                        'description': '可选标准输入内容。',
                    },
                    'timeout_seconds': {
                        'type': 'number',
                        'minimum': 1,
                        'description': '可选超时时间，默认使用当前会话命令超时。',
                    },
                    'max_output_chars': {
                        'type': 'integer',
                        'minimum': 100,
                        'description': '可选输出截断长度，默认使用当前会话输出限制。',
                    },
                },
            },
            handler=resolve_handler(handlers, 'python_exec', 'execution'),
        ),
        AgentTool(
            name='python_package',
            description=(
                '在当前用户独立 Python venv 中检查或安装 Python 包。'
                '用于 python_exec 缺少 pandas、pyarrow、openpyxl 等分析依赖时；'
                '不要通过 bash 执行 pip，也不要安装到项目 .venv。'
            ),
            parameters={
                'type': 'object',
                'properties': {
                    'action': {
                        'type': 'string',
                        'enum': ['show', 'install'],
                        'description': 'show 查看当前 Python 环境和 pip；install 安装 packages。',
                    },
                    'packages': {
                        'type': 'array',
                        'items': {'type': 'string'},
                        'description': '要安装的包名或 pip requirement spec，例如 pandas、pyarrow==15.0.0。',
                    },
                    'timeout_seconds': {
                        'type': 'number',
                        'minimum': 1,
                        'maximum': 600,
                        'description': '安装超时时间，默认 120 秒。',
                    },
                    'max_output_chars': {
                        'type': 'integer',
                        'minimum': 1000,
                        'maximum': 50000,
                    },
                },
                'required': ['action'],
            },
            handler=resolve_handler(handlers, 'python_package', 'execution'),
        ),
        AgentTool(
            name='bash',
            description=(
                '运行真实 shell 命令，例如系统命令、进程控制、git 只读检查或用户已确认的依赖安装。'
                '不要用 bash 执行 python、python3、pip 或 .venv/bin/python；结构化文件分析、'
                'JSON/JSONL 处理、批量校验、数据抽样和快速计算必须优先使用 python_exec。'
                'Python 包安装必须优先使用 python_package。'
            ),
            parameters={
                'type': 'object',
                'properties': {
                    'command': {'type': 'string'},
                },
                'required': ['command'],
            },
            handler=resolve_handler(handlers, 'bash', 'execution'),
        ),
        AgentTool(
            name='sleep',
            description='Pause execution briefly for bounded local wait flows.',
            parameters={
                'type': 'object',
                'properties': {
                    'seconds': {'type': 'number', 'minimum': 0.0, 'maximum': 5.0},
                },
                'required': ['seconds'],
            },
            handler=resolve_handler(handlers, 'sleep', 'execution'),
        ),
    ]
