illusion-code 0.1.0__py3-none-any.whl

illusion/tools/repl_tool.py

@@ -0,0 +1,100 @@
+"""
+最小 REPL shell 执行工具
+=======================
+
+本模块提供在类 REPL 环境中执行 shell 命令的功能。
+
+主要组件：
+    - ReplTool: REPL 风格的 shell 执行工具
+
+使用示例：
+    >>> from illusion.tools import ReplTool
+    >>> tool = ReplTool()
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from illusion.sandbox import SandboxUnavailableError
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+from illusion.utils.shell import create_shell_subprocess
+
+
+class ReplToolInput(BaseModel):
+    """REPL 工具参数。
+
+    属性：
+        command: 要执行的 shell 命令
+        cwd: 可选的工作目录覆盖
+        timeout_seconds: 超时秒数（1-600）
+    """
+
+    command: str = Field(description="Shell command to execute")
+    cwd: str | None = Field(default=None, description="Working directory override")
+    timeout_seconds: int = Field(default=120, ge=1, le=600)
+
+
+class ReplTool(BaseTool):
+    """使用类 REPL 的执行界面执行 shell 命令。
+
+    用于在交互式环境中执行命令。
+    """
+
+    name = "repl"
+    description = "Run shell commands using a REPL-style execution surface."
+    input_model = ReplToolInput
+
+    async def execute(self, arguments: ReplToolInput, context: ToolExecutionContext) -> ToolResult:
+        # 解析工作目录
+        cwd = Path(arguments.cwd).expanduser() if arguments.cwd else context.cwd
+        try:
+            # 创建 shell 子进程
+            process = await create_shell_subprocess(
+                arguments.command,
+                cwd=cwd,
+                stdin=asyncio.subprocess.DEVNULL,  # 防止 Windows 上的句柄继承死锁
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+        except SandboxUnavailableError as exc:
+            return ToolResult(output=str(exc), is_error=True)
+
+        try:
+            # 等待命令完成
+            stdout, stderr = await asyncio.wait_for(
+                process.communicate(),
+                timeout=arguments.timeout_seconds,
+            )
+        except asyncio.TimeoutError:
+            # 超时后终止进程
+            process.kill()
+            await process.wait()
+            return ToolResult(
+                output=f"Command timed out after {arguments.timeout_seconds} seconds",
+                is_error=True,
+            )
+
+        # 收集输出
+        parts = []
+        if stdout:
+            parts.append(stdout.decode("utf-8", errors="replace").rstrip())
+        if stderr:
+            parts.append(stderr.decode("utf-8", errors="replace").rstrip())
+
+        text = "\n".join(part for part in parts if part).strip()
+        if not text:
+            text = "(no output)"
+
+        # 截断过长的输出
+        if len(text) > 12000:
+            text = f"{text[:12000]}\n...[truncated]..."
+
+        return ToolResult(
+            output=text,
+            is_error=process.returncode != 0,
+            metadata={"returncode": process.returncode},
+        )

illusion/tools/send_message_tool.py

@@ -0,0 +1,112 @@
+"""
+发送消息工具
+============
+
+本模块提供向运行中的代理发送消息的功能，对齐标准 SendMessageTool 架构。
+
+主要组件：
+    - SendMessageTool: 向代理发送消息的工具
+
+使用示例：
+    >>> from illusion.tools import SendMessageTool
+    >>> tool = SendMessageTool()
+"""
+
+from __future__ import annotations
+
+import logging
+
+from pydantic import BaseModel, Field
+
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+
+logger = logging.getLogger(__name__)
+
+
+class SendMessageToolInput(BaseModel):
+    """发送消息参数。
+
+    属性：
+        to: 目标代理名称或 ID
+        message: 消息内容
+    """
+
+    to: str = Field(description="Agent name or ID to send the message to")
+    message: str = Field(description="Message content to send")
+
+
+class SendMessageTool(BaseTool):
+    """向运行中的代理发送消息。
+
+    用于与代理通信或发送继续指令。
+    """
+
+    name = "send_message"
+    description = """Send a message to another agent.
+
+Use this tool to communicate with running agents. Messages from teammates are delivered automatically; you don't check an inbox. Refer to teammates by name, never by UUID.
+
+Usage:
+- Send to agent by name: `SendMessage({ to: "researcher", message: "..." })`
+- Send to agent by ID: `SendMessage({ to: "agent_abc123", message: "..." })`
+
+When continuing a completed agent, the agent resumes with its full context preserved.
+"""
+    input_model = SendMessageToolInput
+
+    async def execute(self, arguments: SendMessageToolInput, context: ToolExecutionContext) -> ToolResult:
+        """执行发送消息。
+
+        Args:
+            arguments: 工具输入参数。
+            context: 工具执行上下文。
+
+        Returns:
+            ToolResult: 工具执行结果。
+        """
+        # 延迟导入以避免循环依赖
+        from illusion.swarm.agent_executor import (
+            TeammateMessage,
+            get_active_agent,
+            get_active_agent_by_name,
+        )
+        from illusion.tasks.manager import get_task_manager
+
+        target = arguments.to
+        message_text = arguments.message
+
+        # 首先尝试通过名称查找活跃的进程内代理
+        agent_ctx = get_active_agent_by_name(target)
+        if agent_ctx is None:
+            agent_ctx = get_active_agent(target)
+
+        if agent_ctx is not None:
+            msg = TeammateMessage(
+                text=message_text,
+                from_agent="coordinator",
+            )
+            await agent_ctx.message_queue.put(msg)
+            logger.debug("[SendMessage] Sent message to in-process agent %s", agent_ctx.agent_id)
+            return ToolResult(output=f"Sent message to agent '{target}'")
+
+        # 尝试通过任务管理器写入（子进程代理）
+        try:
+            await get_task_manager().write_to_task(target, message_text)
+            return ToolResult(output=f"Sent message to task '{target}'")
+        except ValueError:
+            pass
+
+        # 尝试查找匹配的任务
+        task_manager = get_task_manager()
+        for task in task_manager.list_tasks(status="running"):
+            if task.description and target in task.description:
+                try:
+                    await task_manager.write_to_task(task.id, message_text)
+                    return ToolResult(output=f"Sent message to task '{task.id}' (matched '{target}')")
+                except ValueError as exc:
+                    return ToolResult(output=str(exc), is_error=True)
+
+        return ToolResult(
+            output=f"No active agent or task found matching '{target}'",
+            is_error=True,
+        )

illusion/tools/shell_common.py

@@ -0,0 +1,187 @@
+"""
+Shell 工具共享模块
+=================
+
+本模块提供 shell 命令执行的共享工具，包括错误码标准化、输出归一化和命令执行器。
+
+主要功能：
+    - ShellErrorCode: 标准化 shell 退出码常量
+    - NormalizedResult: 标准化命令执行结果数据类
+    - OutputNormalizer: 输出解码与归一化处理
+    - CommandExecutor: 统一命令执行器，处理超时、解码、归一化
+
+类说明：
+    - ShellErrorCode: 标准化 shell 退出码常量类
+        - SUCCESS: 成功 (0)
+        - GENERAL_ERROR: 一般错误 (1)
+        - COMMAND_NOT_FOUND: 命令未找到 (127)
+        - TIMEOUT: 超时 (-1)
+        - PERMISSION_DENIED: 权限拒绝 (126)
+        - SIGNAL_BASE: 信号基准 (128 + signal_number)
+    
+    - NormalizedResult: 标准化命令执行结果
+        - output: 输出文本
+        - is_error: 是否为错误
+        - return_code: 返回码
+        - metadata: 元数据字典
+    
+    - OutputNormalizer: 输出解码与归一化处理
+        - decode_output: 健壮解码（UTF-8 → UTF-16LE → locale → replace）
+        - format_result: 生成上下文相关的输出消息
+    
+    - CommandExecutor: 统一命令执行器
+        - run_and_normalize: 等待进程完成，捕获输出，归一化结果
+
+使用示例：
+    >>> from illusion.tools.shell_common import ShellErrorCode, NormalizedResult
+    >>> print(ShellErrorCode.SUCCESS)  # 输出: 0
+    >>> result = NormalizedResult(output="test", is_error=False, return_code=0)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import locale
+from dataclasses import dataclass, field
+from typing import Any
+
+
+# 输出截断阈值（描述中对外暴露此值，修改时需同步更新工具描述文本）
+MAX_OUTPUT_LENGTH = 30_000
+
+
+class ShellErrorCode:
+    """标准化 shell 退出码常量。"""
+
+    SUCCESS = 0
+    GENERAL_ERROR = 1
+    COMMAND_NOT_FOUND = 127
+    TIMEOUT = -1
+    PERMISSION_DENIED = 126
+    SIGNAL_BASE = 128  # 128 + signal_number
+
+
+@dataclass(frozen=True)
+class NormalizedResult:
+    """标准化命令执行结果。"""
+
+    output: str
+    is_error: bool
+    return_code: int
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class OutputNormalizer:
+    """输出解码与归一化处理。"""
+
+    @staticmethod
+    def decode_output(data: bytes) -> str:
+        """健壮解码：UTF-8 → UTF-16LE（如含 null 字节）→ locale → replace。"""
+        if not data:
+            return ""
+
+        encodings: list[str] = ["utf-8"]
+
+        # Windows PowerShell 经常输出 UTF-16LE —— 含 null 字节时优先尝试
+        if b"\x00" in data:
+            encodings.append("utf-16-le")
+
+        preferred = locale.getpreferredencoding(False)
+        if preferred and preferred.lower() not in {"utf-8", "utf8"}:
+            encodings.append(preferred)
+
+        for encoding in encodings:
+            try:
+                return data.decode(encoding)
+            except UnicodeDecodeError:
+                continue
+
+        return data.decode("utf-8", errors="replace")
+
+    @staticmethod
+    def format_result(
+        *,
+        stdout: bytes,
+        stderr: bytes,
+        return_code: int,
+        timed_out: bool,
+        timeout_seconds: int,
+    ) -> NormalizedResult:
+        """生成上下文相关的输出消息，消除 '(no output)' 歧义。"""
+        if timed_out:
+            output = f"Command timed out after {timeout_seconds}s"
+            return NormalizedResult(
+                output=output,
+                is_error=True,
+                return_code=-1,
+                metadata={"returncode": -1, "timed_out": True},
+            )
+
+        decoded_stdout = OutputNormalizer.decode_output(stdout).rstrip()
+        decoded_stderr = OutputNormalizer.decode_output(stderr).rstrip()
+
+        parts = []
+        if decoded_stdout:
+            parts.append(decoded_stdout)
+        if decoded_stderr:
+            parts.append(decoded_stderr)
+
+        text = "\n".join(parts).strip()
+
+        if not text:
+            # 上下文相关的空输出消息
+            if return_code == 0:
+                text = "Command completed successfully (no output produced)\nExit code: 0"
+            else:
+                text = (
+                    f"Process exited with code {return_code} but produced no output\n"
+                    f"Exit code: {return_code}"
+                )
+
+        if len(text) > MAX_OUTPUT_LENGTH:
+            text = f"{text[:MAX_OUTPUT_LENGTH]}\n...[truncated]..."
+
+        return NormalizedResult(
+            output=text,
+            is_error=return_code != 0,
+            return_code=return_code,
+            metadata={"returncode": return_code},
+        )
+
+
+class CommandExecutor:
+    """统一命令执行器，处理超时、解码、归一化。"""
+
+    @staticmethod
+    async def run_and_normalize(
+        process: asyncio.subprocess.Process,
+        *,
+        timeout: int,
+    ) -> NormalizedResult:
+        """等待进程完成，捕获输出，归一化结果。
+
+        调用方负责创建 process（保留各自的 shell/sandbox 逻辑），
+        本方法负责统一的超时、解码、截断和上下文化消息。
+        """
+        try:
+            stdout, stderr = await asyncio.wait_for(
+                process.communicate(),
+                timeout=timeout,
+            )
+        except asyncio.TimeoutError:
+            process.kill()
+            await process.wait()
+            return NormalizedResult(
+                output=f"Command timed out after {timeout}s",
+                is_error=True,
+                return_code=-1,
+                metadata={"returncode": -1, "timed_out": True},
+            )
+
+        return OutputNormalizer.format_result(
+            stdout=stdout or b"",
+            stderr=stderr or b"",
+            return_code=process.returncode if process.returncode is not None else -1,
+            timed_out=False,
+            timeout_seconds=timeout,
+        )

illusion/tools/skill_tool.py

@@ -0,0 +1,86 @@
+"""
+技能内容读取工具
+================
+
+本模块提供读取已加载技能内容的功能，用于执行斜杠命令和自定义技能。
+
+主要组件：
+    - SkillTool: 读取技能内容的工具
+
+使用示例：
+    >>> from illusion.tools import SkillTool
+    >>> tool = SkillTool()
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from illusion.skills import load_skill_registry
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+
+
+class SkillToolInput(BaseModel):
+    """技能查找参数。
+
+    属性：
+        name: 技能名称
+        args: 技能的可选参数
+    """
+
+    name: str = Field(description="Skill name")
+    args: str | None = Field(default=None, description="Optional arguments for the skill")
+
+
+class SkillTool(BaseTool):
+    """返回已加载技能的内容。
+
+    用于执行斜杠命令（/command）或调用自定义技能。
+    """
+
+    name = "skill"
+    description = """Load a skill's instructions so you can then execute them yourself.
+
+This tool does NOT execute anything — it only returns the skill's content (instructions, workflows, examples). You must read the returned content and follow it step by step to complete the task.
+
+When users ask you to perform tasks, check if any of the available skills match. Skills provide specialized capabilities and domain knowledge.
+
+When users reference a "slash command" or "/<something>" (e.g., "/commit", "/review-pr"), they are referring to a skill. Use this tool to load its instructions.
+
+How to use:
+- Call this tool with the skill name and optional arguments
+- The tool returns the skill's instructions — you then execute them
+- Examples:
+  - `skill: "pdf"` — loads the pdf skill's instructions
+  - `skill: "commit", args: "-m 'Fix bug'"` — loads with arguments
+  - `skill: "review-pr", args: "123"` — loads with arguments
+  - `skill: "ms-office-suite:pdf"` — loads using fully qualified name
+
+Important:
+- Available skills are listed in <system-reminder> messages in the conversation
+- When a skill matches the user's request, this is a BLOCKING REQUIREMENT: call this Skill tool to load its instructions BEFORE generating any other response about the task
+- NEVER mention a skill without actually calling this tool
+- Do not load a skill that is already active in the current context
+- Do not use this tool for built-in CLI commands (like /help, /clear, etc.)
+- If you see a <command-name> tag in the current conversation turn, the skill's instructions have ALREADY been loaded — follow the instructions directly instead of calling this tool again"""
+    input_model = SkillToolInput
+
+    def is_read_only(self, arguments: SkillToolInput) -> bool:
+        del arguments
+        return True
+
+    async def execute(self, arguments: SkillToolInput, context: ToolExecutionContext) -> ToolResult:
+        # 加载技能注册表
+        registry = load_skill_registry(context.cwd)
+        # 尝试多种名称格式匹配
+        skill = registry.get(arguments.name) or registry.get(arguments.name.lower()) or registry.get(arguments.name.title())
+        if skill is None:
+            return ToolResult(output=f"Skill not found: {arguments.name}", is_error=True)
+
+        # 获取技能内容
+        content = skill.content
+        # 如果提供了参数，替换 $ARGUMENTS 占位符
+        if arguments.args and "$ARGUMENTS" in content:
+            content = content.replace("$ARGUMENTS", arguments.args)
+
+        return ToolResult(output=content)

illusion/tools/sleep_tool.py

@@ -0,0 +1,62 @@
+"""
+休眠工具
+========
+
+本模块提供暂停执行的功能。
+
+主要组件：
+    - SleepTool: 暂停执行的工具
+
+使用示例：
+    >>> from illusion.tools import SleepTool
+    >>> tool = SleepTool()
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from pydantic import BaseModel, Field
+
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+
+
+class SleepToolInput(BaseModel):
+    """休眠参数。
+
+    属性：
+        seconds: 休眠秒数
+    """
+
+    seconds: float = Field(default=1.0, ge=0.0, le=30.0)
+
+
+class SleepTool(BaseTool):
+    """短暂暂停执行。
+
+    用于等待指定时间后继续执行。
+    """
+
+    name = "sleep"
+    description = """Wait for a specified duration. The user can interrupt the sleep at any time.
+
+Use this when the user tells you to sleep or rest, when you have nothing to do, or when you're waiting for something.
+
+You may receive <tick> prompts - these are periodic check-ins. Look for useful work to do before sleeping.
+
+You can call this concurrently with other tools - it won't interfere with them.
+
+Prefer this over `Bash(sleep ...)` - it doesn't hold a shell process.
+
+Each wake-up costs an API call, but the prompt cache expires after 5 minutes of inactivity - balance accordingly."""
+    input_model = SleepToolInput
+
+    def is_read_only(self, arguments: SleepToolInput) -> bool:
+        del arguments
+        return True
+
+    async def execute(self, arguments: SleepToolInput, context: ToolExecutionContext) -> ToolResult:
+        del context
+        # 异步休眠
+        await asyncio.sleep(arguments.seconds)
+        return ToolResult(output=f"Slept for {arguments.seconds} seconds")

illusion/tools/structured_output_tool.py

@@ -0,0 +1,58 @@
+"""
+结构化输出工具
+=============
+
+本模块提供以模式验证的 JSON 格式返回最终响应的功能。
+
+主要组件：
+    - StructuredOutputTool: 结构化输出工具
+
+使用示例：
+    >>> from illusion.tools import StructuredOutputTool
+    >>> tool = StructuredOutputTool()
+"""
+
+from __future__ import annotations
+
+import json
+
+from pydantic import BaseModel, Field
+
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+
+
+class StructuredOutputToolInput(BaseModel):
+    """任意结构化 payload。
+
+    属性：
+        structured_output: 结构化输出 payload
+    """
+
+    structured_output: dict[str, object] = Field(
+        default_factory=dict,
+        description="Structured output payload",
+    )
+
+
+class StructuredOutputTool(BaseTool):
+    """以结构化 JSON 形式返回最终响应。
+
+    用于按照请求的格式返回结构化输出。
+    """
+
+    name = "structured_output"
+    description = """Use this tool to return your final response in the requested structured format. You MUST call this tool exactly once at the end of your response to provide the structured output."""
+    input_model = StructuredOutputToolInput
+
+    def is_read_only(self, arguments: StructuredOutputToolInput) -> bool:
+        del arguments
+        return True
+
+    async def execute(
+        self,
+        arguments: StructuredOutputToolInput,
+        context: ToolExecutionContext,
+    ) -> ToolResult:
+        del context
+        output = json.dumps(arguments.structured_output, ensure_ascii=False)
+        return ToolResult(output=output)