illusion-code 0.1.0__py3-none-any.whl

illusion/tools/team_create_tool.py

@@ -0,0 +1,236 @@
+"""
+团队创建工具
+============
+
+本模块提供 team_create 工具，用于创建多代理协作团队。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+from illusion.state import AppStateStore
+from illusion.swarm.team_helpers import (
+    TEAM_LEAD_NAME,
+    ensure_tasks_dir,
+    get_team_file_path,
+    read_team_file,
+    register_team_for_session_cleanup,
+    reset_task_list,
+    sanitize_name,
+    write_team_file,
+)
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+
+
+class TeamCreateToolInput(BaseModel):
+    """team_create 输入参数。"""
+
+    team_name: str = Field(description="Name for the new team to create.")
+    description: str | None = Field(default=None, description="Team description/purpose.")
+    agent_type: str | None = Field(
+        default=None,
+        description=(
+            'Type/role of the team lead (e.g., "researcher", "test-runner"). '
+            "Used for team file and inter-agent coordination."
+        ),
+    )
+
+
+def _generate_unique_team_name(provided_name: str) -> str:
+    """生成唯一团队名（若已存在则回退到随机 slug）。"""
+    if read_team_file(provided_name) is None:
+        return provided_name
+    return f"team-{uuid4().hex[:8]}"
+
+
+class TeamCreateTool(BaseTool):
+    """创建新的多代理团队。"""
+
+    name = "team_create"
+    description = """# TeamCreate
+
+## When to Use
+
+Use this tool proactively whenever:
+- The user explicitly asks to use a team, swarm, or group of agents
+- The user mentions wanting agents to work together, coordinate, or collaborate
+- A task is complex enough that it would benefit from parallel work by multiple agents (e.g., building a full-stack feature with frontend and backend work, refactoring a codebase while keeping tests passing, implementing a multi-step project with research, planning, and coding phases)
+
+When in doubt about whether a task warrants a team, prefer spawning a team.
+
+## Choosing Agent Types for Teammates
+
+When spawning teammates via the Agent tool, choose the `subagent_type` based on what tools the agent needs for its task. Each agent type has a different set of available tools — match the agent to the work:
+
+- **Read-only agents** (e.g., Explore, Plan) cannot edit or write files. Only assign them research, search, or planning tasks. Never assign them implementation work.
+- **Full-capability agents** (e.g., general-purpose) have access to all tools including file editing, writing, and bash. Use these for tasks that require making changes.
+- **Custom agents** defined in `.illusion/agents/` may have their own tool restrictions. Check their descriptions to understand what they can and cannot do.
+
+Always review the agent type descriptions and their available tools listed in the Agent tool prompt before selecting a `subagent_type` for a teammate.
+
+Create a new team to coordinate multiple agents working on a project. Teams have a 1:1 correspondence with task lists (Team = TaskList).
+
+```json
+{
+  "team_name": "my-project",
+  "description": "Working on feature X"
+}
+```
+
+This creates:
+- A team file at `~/.illusion/teams/{team-name}/config.json`
+- A corresponding task list directory at `~/.illusion/data/tasks/{team-name}/`
+
+**Note**: If a team with the same name already exists, a random suffix is appended to ensure uniqueness (e.g., `my-project` may become `team-a1b2c3d4`). The actual name used is returned in the tool output.
+
+## Team Workflow
+
+1. **Create a team** with TeamCreate - this creates both the team and its task list
+2. **Create tasks** using the Task tools (TaskCreate, TaskList, etc.) - they automatically use the team's task list
+3. **Spawn teammates** using the Agent tool with `team_name` and `name` parameters to create teammates that join the team
+4. **Assign tasks** using TaskUpdate with `owner` to give tasks to idle teammates
+5. **Teammates work on assigned tasks** and mark them completed via TaskUpdate
+6. **Teammates go idle between turns** - after each turn, teammates automatically go idle and send a notification. IMPORTANT: Be patient with idle teammates! Don't comment on their idleness until it actually impacts your work.
+7. **Shutdown your team** - when the task is completed, gracefully shut down your teammates via `SendMessage` with a shutdown request, then call TeamDelete.
+
+## Task Ownership
+
+Tasks are assigned using TaskUpdate with the `owner` parameter. Any agent can set or change task ownership via TaskUpdate.
+
+## Automatic Message Delivery
+
+**IMPORTANT**: Messages from teammates are automatically delivered to you. You do NOT need to manually check your inbox.
+
+When you spawn teammates:
+- They will send you messages when they complete tasks or need help
+- These messages appear automatically as new conversation turns (like user messages)
+- If you're busy (mid-turn), messages are queued and delivered when your turn ends
+- The UI shows a brief notification with the sender's name when messages are waiting
+
+Messages will be delivered automatically.
+
+When reporting on teammate messages, you do NOT need to quote the original message—it's already rendered to the user.
+
+## Teammate Idle State
+
+Teammates go idle after every turn—this is completely normal and expected. A teammate going idle immediately after sending you a message does NOT mean they are done or unavailable. Idle simply means they are waiting for input.
+
+- **Idle teammates can receive messages.** Sending a message to an idle teammate wakes them up and they will process it normally.
+- **Idle notifications are automatic.** The system sends an idle notification whenever a teammate's turn ends. You do not need to react to idle notifications unless you want to assign new work or send a follow-up message.
+- **Do not treat idle as an error.** A teammate sending a message and then going idle is the normal flow—they sent their message and are now waiting for a response.
+- **Peer DM visibility.** When a teammate sends a DM to another teammate, a brief summary is included in their idle notification. This gives you visibility into peer collaboration without the full message content. You do not need to respond to these summaries — they are informational.
+
+## Discovering Team Members
+
+Teammates can read the team config file to discover other team members:
+- **Team config location**: `~/.illusion/teams/{team-name}/config.json`
+
+The config file contains a `members` array with each teammate's:
+- `name`: Human-readable name (**always use this** for messaging and task assignment)
+- `agentId`: Unique identifier (for reference only - do not use for communication)
+- `agentType`: Role/type of the agent
+
+**IMPORTANT**: Always refer to teammates by their NAME (e.g., "team-lead", "researcher", "tester"). Names are used for:
+- `to` when sending messages
+- Identifying task owners
+
+Example of reading team config:
+```
+Use the Read tool to read ~/.illusion/teams/{team-name}/config.json
+```
+
+## Task List Coordination
+
+Teams share a task list that all teammates can access at `~/.illusion/data/tasks/{team-name}/`.
+
+Teammates should:
+1. Check TaskList periodically, **especially after completing each task**, to find available work or see newly unblocked tasks
+2. Claim unassigned, unblocked tasks with TaskUpdate (set `owner` to your name). **Prefer tasks in ID order** (lowest ID first) when multiple tasks are available, as earlier tasks often set up context for later ones
+3. Create new tasks with `TaskCreate` when identifying additional work
+4. Mark tasks as completed with `TaskUpdate` when done, then check TaskList for next work
+5. Coordinate with other teammates by reading the task list status
+6. If all available tasks are blocked, notify the team lead or help resolve blocking tasks
+
+**IMPORTANT notes for communication with your team**:
+- Do not use terminal tools to view your team's activity; always send a message to your teammates (and remember, refer to them by name).
+- Your team cannot hear you if you do not use the SendMessage tool. Always send a message to your teammates if you are responding to them.
+- Do NOT send structured JSON status messages like `{"type":"idle",...}` or `{"type":"task_completed",...}`. Just communicate in plain text when you need to message teammates.
+- Use TaskUpdate to mark tasks completed.
+- If you are an agent in the team, the system will automatically send idle notifications to the team lead when you stop.
+"""
+    input_model = TeamCreateToolInput
+
+    async def execute(self, arguments: TeamCreateToolInput, context: ToolExecutionContext) -> ToolResult:
+        team_name = arguments.team_name.strip()
+        if not team_name:
+            return ToolResult(output="team_name is required for team_create", is_error=True)
+
+        app_state_store = context.metadata.get("app_state_store")
+        if isinstance(app_state_store, AppStateStore):
+            existing_team = app_state_store.get().team_context
+            if isinstance(existing_team, dict) and existing_team.get("teamName"):
+                active_team = str(existing_team["teamName"])
+                return ToolResult(
+                    output=(
+                        f'Already leading team "{active_team}". '
+                        "A leader can only manage one team at a time. "
+                        "Use team_delete to end the current team before creating a new one."
+                    ),
+                    is_error=True,
+                )
+
+        final_team_name = _generate_unique_team_name(team_name)
+        lead_agent_id = f"{TEAM_LEAD_NAME}@{sanitize_name(final_team_name)}"
+        lead_agent_type = arguments.agent_type or TEAM_LEAD_NAME
+        team_file_path = str(get_team_file_path(final_team_name))
+        session_id = str(context.metadata.get("session_id") or "")
+
+        team_file = {
+            "name": final_team_name,
+            "description": arguments.description,
+            "createdAt": int(time.time() * 1000),
+            "leadAgentId": lead_agent_id,
+            "leadSessionId": session_id,
+            "members": [
+                {
+                    "agentId": lead_agent_id,
+                    "name": TEAM_LEAD_NAME,
+                    "agentType": lead_agent_type,
+                    "joinedAt": int(time.time() * 1000),
+                    "tmuxPaneId": "",
+                    "cwd": str(context.cwd),
+                    "subscriptions": [],
+                }
+            ],
+        }
+
+        write_team_file(final_team_name, team_file)
+        register_team_for_session_cleanup(final_team_name)
+
+        task_list_id = sanitize_name(final_team_name)
+        reset_task_list(task_list_id)
+        ensure_tasks_dir(task_list_id)
+        os.environ["ILLUSION_TASK_LIST_ID"] = task_list_id
+
+        if isinstance(app_state_store, AppStateStore):
+            app_state_store.set(
+                team_context={
+                    "teamName": final_team_name,
+                    "teamFilePath": team_file_path,
+                    "leadAgentId": lead_agent_id,
+                }
+            )
+
+        output = {
+            "team_name": final_team_name,
+            "team_file_path": team_file_path,
+            "lead_agent_id": lead_agent_id,
+        }
+        return ToolResult(output=json.dumps(output, ensure_ascii=False))
+

illusion/tools/team_delete_tool.py

@@ -0,0 +1,104 @@
+"""
+团队删除工具
+============
+
+本模块提供 team_delete 工具，用于清理团队相关资源。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+from pydantic import BaseModel
+
+from illusion.state import AppStateStore
+from illusion.swarm.team_helpers import (
+    TEAM_LEAD_NAME,
+    cleanup_team_directories,
+    read_team_file,
+    unregister_team_for_session_cleanup,
+)
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+
+
+class TeamDeleteToolInput(BaseModel):
+    """team_delete 输入参数（无参数）。"""
+
+
+class TeamDeleteTool(BaseTool):
+    """删除当前团队并清理关联目录。"""
+
+    name = "team_delete"
+    description = """# TeamDelete
+
+Remove team and task directories when the swarm work is complete.
+
+This operation:
+- Removes the team directory (`~/.illusion/teams/{team-name}/`)
+- Removes the task directory (`~/.illusion/data/tasks/{team-name}/`)
+- Clears team context from the current session
+
+**IMPORTANT**: TeamDelete will fail if the team still has active members. Gracefully terminate teammates via `SendMessage` first, then call TeamDelete after all teammates have shut down.
+
+Use this when all teammates have finished their work and you want to clean up the team resources. The team name is automatically determined from the current session's team context.
+"""
+    input_model = TeamDeleteToolInput
+
+    async def execute(self, arguments: TeamDeleteToolInput, context: ToolExecutionContext) -> ToolResult:
+        del arguments
+        app_state_store = context.metadata.get("app_state_store")
+
+        team_name: str | None = None
+        if isinstance(app_state_store, AppStateStore):
+            team_context = app_state_store.get().team_context
+            if isinstance(team_context, dict):
+                raw = team_context.get("teamName")
+                if isinstance(raw, str) and raw.strip():
+                    team_name = raw
+
+        if team_name:
+            team_file = read_team_file(team_name)
+            if team_file:
+                members = team_file.get("members", [])
+                if isinstance(members, list):
+                    non_lead_members = [
+                        member
+                        for member in members
+                        if isinstance(member, dict) and member.get("name") != TEAM_LEAD_NAME
+                    ]
+                    active_members = [
+                        member
+                        for member in non_lead_members
+                        if member.get("isActive", member.get("is_active", True)) is not False
+                    ]
+                    if active_members:
+                        member_names = ", ".join(str(member.get("name", "")) for member in active_members)
+                        output = {
+                            "success": False,
+                            "message": (
+                                f"Cannot cleanup team with {len(active_members)} active member(s): "
+                                f"{member_names}. Use SendMessage to gracefully terminate teammates first."
+                            ),
+                            "team_name": team_name,
+                        }
+                        return ToolResult(output=json.dumps(output, ensure_ascii=False))
+
+            cleanup_team_directories(team_name)
+            unregister_team_for_session_cleanup(team_name)
+            os.environ.pop("ILLUSION_TASK_LIST_ID", None)
+
+        if isinstance(app_state_store, AppStateStore):
+            app_state_store.set(team_context=None)
+
+        output = {
+            "success": True,
+            "message": (
+                f'Cleaned up directories and worktrees for team "{team_name}"'
+                if team_name
+                else "No team name found, nothing to clean up"
+            ),
+            "team_name": team_name,
+        }
+        return ToolResult(output=json.dumps(output, ensure_ascii=False))
+

illusion/tools/todo_write_tool.py

@@ -0,0 +1,198 @@
+"""
+TODO写入工具模块
+================
+
+本模块提供编码会话结构化任务列表的管理功能。
+
+主要功能：
+    - 创建和管理结构化任务列表
+    - 跟踪当前编码会话的进度
+    - 展示任务的整体进度给用户
+
+类说明：
+    - TodoWriteToolInput: TODO写入工具输入参数
+    - TodoWriteTool: TODO写入工具类
+
+使用示例：
+    >>> # 通过全量替换更新任务列表
+    >>> # 工具将任务状态存入执行结果的元数据中
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+
+
+class TodoItem(BaseModel):
+    """TODO项数据模型
+    
+    Attributes:
+        content: 任务描述（祈使形式）
+        status: 任务状态（pending/in_progress/completed）
+        activeForm: 执行时显示的进行时形式
+    """
+
+    content: str = Field(min_length=1)
+    status: str = Field(pattern=r"^(pending|in_progress|completed)$")
+    activeForm: str = Field(min_length=1)
+
+
+class TodoWriteToolInput(BaseModel):
+    """TODO写入工具的参数模型
+    
+    Attributes:
+        todos: TODO项列表，每项包含content/status/activeForm
+    """
+
+    todos: list[TodoItem] = Field(description="List of todo items to update")
+
+
+class TodoWriteTool(BaseTool):
+    """创建和管理当前编码会话的结构化任务列表。
+    
+    通过全量替换的方式更新任务列表，要删除某个任务只需在下一次调用中不再包含它。
+    这有助于您跟踪进度、组织复杂任务，并展示给用户您的周到性。
+    它还帮助用户了解任务进度和整体请求进度。
+
+    何时使用此工具：
+    在以下场景中主动使用此工具：
+
+    1. 复杂的多步骤任务 - 当任务需要3个或更多不同步骤或操作时
+    2. 非平凡和复杂的任务 - 需要仔细规划或多个操作的任务
+    3. 用户明确请求TODO列表 - 当用户直接要求您使用TODO列表时
+    4. 用户提供多个任务 - 当用户提供要做的事情列表时（用数字或逗号分隔）
+    5. 收到新指令后 - 立即将用户需求捕获为TODO
+    6. 开始任务时 - 在开始工作之前将其标记为in_progress。理想情况下，您应该一次只有一个TODO为in_progress
+    7. 完成任务后 - 立即将其标记为completed，并在实施过程中添加发现的新后续任务
+
+    何时不使用此工具：
+
+    仅对简单任务跳过使用此工具：
+    - 只有单一、直接的任务
+    - 任务 trivial，跟踪它没有组织好处
+    - 任务可以在3个简单步骤内完成
+    - 任务纯粹是对话式或信息性的
+
+    注意：如果只有一个简单的任务要处理，您不应该使用此工具。
+    在这种情况下，您最好直接完成任务。
+
+    任务状态和管理：
+
+    1. **任务状态**：使用这些状态跟踪进度：
+       - pending: 任务尚未开始
+       - in_progress: 当前正在处理（一次限制为一个任务）
+       - completed: 任务成功完成
+
+       **重要**：任务描述必须有两种形式：
+       - content: 描述需要做什么的祈使形式（例如，"运行测试"、"构建项目"）
+       - activeForm: 执行期间显示的现在进行时形式（例如，"正在运行测试"、"正在构建项目"）
+
+    2. **任务管理**：
+       - 工作时实时更新任务状态
+       - 完成后立即标记任务（不要批量完成）
+       - 任何时候必须恰好有一个任务为in_progress（不少于，也不多于）
+       - 在开始新任务之前完成当前任务
+       - 从列表中完全删除不再相关的任务
+
+    3. **任务完成要求**：
+       - 仅在完全完成时才将任务标记为completed
+       - 如果遇到错误、阻塞或无法完成，请保持任务为in_progress
+       - 被阻塞时，创建描述需要解决的新任务
+       - 永远不要将任务标记为completed如果：
+         - 测试失败
+         - 实现不完整
+         - 遇到未解决的错误
+         - 找不到必要的文件或依赖
+
+    4. **任务分解**：
+       - 创建具体、可操作的项目
+       - 将复杂任务分解为更小、可管理的步骤
+       - 使用清晰、描述性的任务名称
+       - 始终提供两种形式：
+         - content: "修复认证bug"
+         - activeForm: "正在修复认证bug"
+
+    如有疑问，请使用此工具。主动的任务管理展示 attentive 并确保您成功完成所有要求。
+    """
+
+    name = "todo_write"
+    description = """Use this tool to create and manage a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
+It also helps the user understand the progress of the task and overall progress of their requests.
+
+## When to Use This Tool
+Use this tool proactively in these scenarios:
+
+1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
+2. Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
+3. User explicitly requests todo list - When the user directly asks you to use the todo list
+4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
+5. After receiving new instructions - Immediately capture user requirements as todos
+6. When you start working on a task - Mark it as in_progress BEFORE beginning work. Ideally you should only have one todo as in_progress at a time
+7. After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation
+
+## When NOT to Use This Tool
+
+Skip using this tool when:
+1. There is only a single, straightforward task
+2. The task is trivial and tracking it provides no organizational benefit
+3. The task can be completed in less than 3 trivial steps
+4. The task is purely conversational or informational
+
+NOTE that you should not use this tool if there is only one trivial task to do. In this case you are better off just doing the task directly.
+
+## Task States and Management
+
+1. **Task States**: Use these states to track progress:
+   - pending: Task not yet started
+   - in_progress: Currently working on (limit to ONE task at a time)
+   - completed: Task finished successfully
+
+   **IMPORTANT**: Task descriptions must have two forms:
+   - content: The imperative form describing what needs to be done (e.g., "Run tests", "Build the project")
+   - activeForm: The present continuous form shown during execution (e.g., "Running tests", "Building the project")
+
+2. **Task Management**:
+   - Update task status in real-time as you work
+   - Mark tasks complete IMMEDIATELY after finishing (don't batch completions)
+   - Exactly ONE task must be in_progress at any time (not less, not more)
+   - Complete current tasks before starting new ones
+   - Remove tasks that are no longer relevant from the list entirely
+
+3. **Task Completion Requirements**:
+   - ONLY mark a task as completed when you have FULLY accomplished it
+   - If you encounter errors, blockers, or cannot finish, keep the task as in_progress
+   - When blocked, create a new task describing what needs to be resolved
+   - Never mark a task as completed if:
+     - Tests are failing
+     - Implementation is partial
+     - You encountered unresolved errors
+     - You couldn't find necessary files or dependencies
+
+4. **Task Breakdown**:
+   - Create specific, actionable items
+   - Break complex tasks into smaller, manageable steps
+   - Use clear, descriptive task names
+   - Always provide both forms:
+     - content: "Fix authentication bug"
+     - activeForm: "Fixing authentication bug"
+
+When in doubt, use this tool. Being proactive with task management demonstrates attentiveness and ensures you complete all requirements successfully."""
+    input_model = TodoWriteToolInput
+
+    async def execute(self, arguments: TodoWriteToolInput, context: ToolExecutionContext) -> ToolResult:
+        """执行TODO写入操作
+        
+        Args:
+            arguments: 工具输入参数
+            context: 工具执行上下文
+        
+        Returns:
+            ToolResult: 执行结果
+        """
+        todos_data = [item.model_dump() for item in arguments.todos]
+        all_done = all(item.status == "completed" for item in arguments.todos)
+        if all_done and len(arguments.todos) >= 1:
+            todos_data = []
+        return ToolResult(output="Todos updated", metadata={"todos": todos_data})