crabcode 0.1.6__py3-none-win_amd64.whl

crabcode_core/tools/skill.py

@@ -0,0 +1,108 @@
+"""SkillTool — lets the model invoke user-defined skills."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from crabcode_core.types.tool import PermissionBehavior, PermissionResult, Tool, ToolResult
+
+if TYPE_CHECKING:
+    from crabcode_core.skills.loader import SkillDefinition
+    from crabcode_core.types.tool import ToolContext
+
+
+class SkillTool(Tool):
+    """Execute a user-defined skill loaded from SKILL.md files.
+
+    The model calls this tool when the user invokes a skill by name (e.g.
+    ``/commit``) or when the task naturally matches a skill's description.
+    The tool expands the skill's Markdown content and returns it so the model
+    can follow the instructions.
+    """
+
+    name = "Skill"
+    is_read_only = True
+    is_concurrency_safe = True
+
+    input_schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "skill_name": {
+                "type": "string",
+                "description": "Name of the skill to execute.",
+            },
+            "user_input": {
+                "type": "string",
+                "description": "The user's additional input or context for the skill.",
+            },
+        },
+        "required": ["skill_name"],
+    }
+
+    def __init__(self, skills: list[SkillDefinition]) -> None:
+        self._skills = skills
+        self._skill_map = {s.name: s for s in skills}
+
+    async def get_prompt(self, **kwargs: Any) -> str:
+        lines = [
+            "Execute a user-defined skill.\n",
+            "When a user invokes /<skill-name> or their request clearly matches a skill's",
+            "description, call this tool with the matching skill_name BEFORE generating",
+            "any other response. The tool will return the skill's instructions, which you",
+            "should then follow to complete the task.\n",
+        ]
+
+        if self._skills:
+            lines.append("## Available skills\n")
+            for skill in self._skills:
+                summary = skill.when_to_use or skill.description
+                lines.append(f"- {skill.name}: {summary}")
+
+        lines.append(
+            "IMPORTANT: Only invoke skills listed above. "
+            "Do not guess or invent skill names."
+        )
+        return "\n".join(lines)
+
+    async def validate_input(self, tool_input: dict[str, Any]) -> str | None:
+        skill_name = tool_input.get("skill_name", "")
+        if skill_name not in self._skill_map:
+            available = ", ".join(self._skill_map) or "(none)"
+            return f"Unknown skill '{skill_name}'. Available skills: {available}"
+        return None
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: ToolContext,
+    ) -> PermissionResult:
+        return PermissionResult(behavior=PermissionBehavior.ALLOW)
+
+    async def call(
+        self,
+        tool_input: dict[str, Any],
+        context: ToolContext,
+    ) -> ToolResult:
+        skill_name = tool_input.get("skill_name", "")
+        user_input = tool_input.get("user_input", "")
+
+        skill = self._skill_map.get(skill_name)
+        if not skill:
+            available = ", ".join(self._skill_map) or "(none)"
+            return ToolResult(
+                is_error=True,
+                result_for_model=f"Unknown skill '{skill_name}'. Available: {available}",
+            )
+
+        content = skill.content
+        if user_input:
+            # Support explicit $USER_INPUT placeholder; otherwise append
+            if "$USER_INPUT" in content:
+                content = content.replace("$USER_INPUT", user_input)
+            else:
+                content = f"{content}\n\nUser input: {user_input}"
+
+        return ToolResult(
+            result_for_model=content,
+            result_for_display=f"[Skill: {skill_name}]",
+        )

crabcode_core/tools/switch_mode.py

@@ -0,0 +1,213 @@
+"""SwitchMode tool — allows the agent to request a mode switch and submit plans."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from crabcode_core.types.event import ModeChangeEvent, PlanReadyEvent
+from crabcode_core.types.tool import Tool, ToolContext, ToolResult
+
+
+class SwitchModeTool(Tool):
+    name = "SwitchMode"
+    description = "Switch between plan mode (read-only planning) and agent mode (full execution). In plan mode, use this to submit a structured execution plan."
+    is_read_only = True
+    is_concurrency_safe = False
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "target_mode": {
+                "type": "string",
+                "enum": ["agent", "plan"],
+                "description": "The mode to switch to.",
+            },
+            "explanation": {
+                "type": "string",
+                "description": "Brief explanation for why the mode switch is requested.",
+            },
+            "plan": {
+                "type": "object",
+                "description": (
+                    "A structured execution plan to submit when switching from plan to agent mode. "
+                    "Required when switching from plan to agent. Schema: "
+                    '{"title": str, "summary": str, "steps": [{"id": str, "title": str, '
+                    '"description": str, "files": [str], "depends_on": [str], "subagent_type": str}]}'
+                ),
+            },
+        },
+        "required": ["target_mode"],
+    }
+
+    # Set by CoreSession before each query loop turn so the tool
+    # prompt can reflect the current mode.
+    current_mode: str = "agent"
+
+    def _build_description(self) -> str:
+        """Build the dynamic tool description based on current_mode."""
+        base = self.description
+        if self.current_mode == "plan":
+            return (
+                base
+                + " IMPORTANT: You are currently in plan mode — "
+                "only use target_mode='agent' (with a plan) to submit your plan. "
+                "Do NOT use target_mode='plan' as you are already in plan mode."
+            )
+        return (
+            base
+            + " IMPORTANT: You are currently in agent mode — "
+            "only use target_mode='plan' if you want to switch to read-only planning. "
+            "Do NOT use target_mode='agent' as you are already in agent mode."
+        )
+
+    def to_api_schema(self) -> dict[str, Any]:
+        """Override to use dynamic description instead of cached prompt."""
+        return {
+            "name": self.name,
+            "description": self._build_description(),
+            "input_schema": self.input_schema,
+        }
+
+    async def get_prompt(self, **kwargs: Any) -> str:
+        mode_note = ""
+        if self.current_mode == "plan":
+            mode_note = (
+                "\n\nIMPORTANT: You are currently in plan mode. "
+                "Do NOT call this tool with target_mode='plan' — you are already in plan mode. "
+                "Use target_mode='agent' only when you are ready to submit your execution plan."
+            )
+        else:
+            mode_note = (
+                "\n\nIMPORTANT: You are currently in agent mode. "
+                "Only call this tool if you want to switch to plan mode for read-only planning. "
+                "Do NOT call this tool with target_mode='agent' unless you are in plan mode "
+                "submitting a plan."
+            )
+
+        return (
+            "Switch between plan mode (read-only analysis and planning) and agent mode "
+            "(full tool access for executing changes).\n\n"
+            "Use cases:\n"
+            "- In plan mode: after gathering context and designing a plan, call this tool "
+            "with target_mode='agent' and a structured plan in the 'plan' field to submit "
+            "the plan to the interface for review. This ends the current turn. Do not call "
+            "other tools afterwards, and do not assume execution has started.\n"
+            "- In agent mode: call with target_mode='plan' to switch to read-only planning mode.\n\n"
+            "When submitting a plan (switching plan -> agent), the 'plan' field is required. "
+            "The plan should contain:\n"
+            "- title: short plan title\n"
+            "- summary: 1-3 sentence overview\n"
+            "- steps: array of execution steps, each with:\n"
+            "  - id: unique short identifier (e.g. 's1', 's2')\n"
+            "  - title: one-line step description\n"
+            "  - description: detailed prompt for the sub-agent executing this step\n"
+            "  - files: file paths this step will modify\n"
+            "  - depends_on: ids of steps that must complete first (for DAG scheduling)\n"
+            "  - subagent_type: 'generalPurpose' (default) or 'explore'\n"
+            "  Do not set 'status' on steps — they are pending until execution.\n\n"
+            "Steps with no dependencies run in parallel. Design steps for maximum parallelism."
+            + mode_note
+        )
+
+    async def validate_input(self, tool_input: dict[str, Any]) -> str | None:
+        target = tool_input.get("target_mode")
+        if target not in ("agent", "plan"):
+            return "target_mode must be 'agent' or 'plan'"
+        if target == self.current_mode:
+            return (
+                f"You are already in {target} mode. "
+                f"Switching to the same mode is unnecessary — continue with your current work."
+            )
+        if self.current_mode == "plan" and target == "agent":
+            plan_data = tool_input.get("plan")
+            if not isinstance(plan_data, dict) or not plan_data:
+                return (
+                    "A non-empty structured plan is required when submitting "
+                    "a plan-mode result for review"
+                )
+        return None
+
+    async def call(
+        self,
+        tool_input: dict[str, Any],
+        context: ToolContext,
+    ) -> ToolResult:
+        target_mode = tool_input["target_mode"]
+        explanation = tool_input.get("explanation", "")
+        plan_data = tool_input.get("plan")
+
+        # This is a security boundary as well as input validation.  A model can
+        # call tools directly even when a provider does not enforce every JSON
+        # schema constraint, so never let a bare plan -> agent request emit a
+        # mode-change event.
+        if self.current_mode == "plan" and target_mode == "agent" and (
+            not isinstance(plan_data, dict) or not plan_data
+        ):
+            return ToolResult(
+                result_for_model=(
+                    "Cannot leave plan mode without submitting a non-empty "
+                    "structured plan for user review."
+                ),
+                is_error=True,
+            )
+
+        if target_mode == "agent" and plan_data:
+            from crabcode_core.plan.types import ExecutionPlan
+
+            try:
+                plan = ExecutionPlan.from_dict(plan_data)
+            except Exception as e:
+                return ToolResult(
+                    result_for_model=f"Invalid plan structure: {e}",
+                    is_error=True,
+                )
+
+            errors = plan.validate_dag()
+            if errors:
+                return ToolResult(
+                    result_for_model=f"Plan validation failed:\n" + "\n".join(f"- {e}" for e in errors),
+                    is_error=True,
+                )
+
+            plan.prepare_for_execution()
+            if context.session and hasattr(context.session, "set_plan"):
+                context.session.set_plan(plan.to_dict())
+
+            if context.tool_event_queue:
+                await context.tool_event_queue.put(
+                    PlanReadyEvent(plan=plan.to_dict())
+                )
+
+        # A plan submission is not approval to execute it.  Keep the session in
+        # plan mode until the interface receives an explicit user confirmation.
+        # Agent -> plan requests still take effect immediately.
+        submitting_plan = (
+            self.current_mode == "plan"
+            and target_mode == "agent"
+            and isinstance(plan_data, dict)
+        )
+        if (
+            not submitting_plan
+            and context.session
+            and hasattr(context.session, "switch_mode")
+        ):
+            context.session.switch_mode(target_mode)
+        if context.tool_event_queue and not submitting_plan:
+            await context.tool_event_queue.put(
+                ModeChangeEvent(mode=target_mode, reason=explanation)
+            )
+
+        if target_mode == "agent" and plan_data:
+            return ToolResult(
+                result_for_model=(
+                    "Execution plan submitted for user review; the session remains "
+                    "in read-only plan mode. "
+                    f"The plan has {len(plan_data.get('steps', []))} steps. "
+                    f"Return control to the interface now so the user can choose whether to "
+                    f"execute, revise, or cancel it. Do not call more tools in this turn."
+                ),
+            )
+
+        return ToolResult(
+            result_for_model=f"Mode switch to '{target_mode}' requested. {explanation}",
+        )

crabcode_core/tools/team.py

@@ -0,0 +1,329 @@
+"""Agent Team tools — LLM-callable tools for managing teams.
+
+These tools allow the lead agent to create teams, spawn teammates,
+send messages, manage tasks, and shut down teams through tool calls.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from crabcode_core.team.models import TeammateRole
+from crabcode_core.types.tool import Tool, ToolContext, ToolResult
+
+
+class TeamCreateTool(Tool):
+    name = "TeamCreate"
+    description = "Create a new agent team for coordinated multi-agent work."
+    is_read_only = False
+    is_concurrency_safe = True
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "name": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Name for the team (also used as team ID).",
+            },
+            "max_teammates": {
+                "type": "integer",
+                "description": "Maximum number of teammates (default: 8).",
+            },
+        },
+        "required": ["name"],
+    }
+
+    async def call(self, tool_input: dict[str, Any], context: ToolContext) -> ToolResult:
+        manager = context.team_manager
+        if not manager:
+            return ToolResult(result_for_model="Error: team manager unavailable", is_error=True)
+        try:
+            team_id = await manager.create_team(
+                tool_input["name"],
+                max_teammates=tool_input.get("max_teammates"),
+            )
+            return ToolResult(
+                data={"team_id": team_id},
+                result_for_model=f"Team created: {team_id}",
+            )
+        except (ValueError, RuntimeError) as exc:
+            return ToolResult(result_for_model=f"Error: {exc}", is_error=True)
+
+
+class TeamSpawnTool(Tool):
+    name = "TeamSpawn"
+    description = "Spawn a teammate agent within a team."
+    is_read_only = False
+    is_concurrency_safe = True
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "team_id": {
+                "type": "string",
+                "description": "The team to add the teammate to.",
+            },
+            "role": {
+                "type": "string",
+                "enum": ["lead", "worker", "researcher", "reviewer"],
+                "description": "Role for the teammate (default: worker).",
+            },
+            "prompt": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The task/prompt for the teammate agent.",
+            },
+            "name": {
+                "type": "string",
+                "description": "Optional display name for the teammate.",
+            },
+            "model_profile": {
+                "type": "string",
+                "description": (
+                    "Optional named model profile configured under settings.models "
+                    "(enables multi-model teams). Do not pass a provider model ID."
+                ),
+            },
+        },
+        "required": ["team_id", "prompt"],
+    }
+
+    async def call(self, tool_input: dict[str, Any], context: ToolContext) -> ToolResult:
+        manager = context.team_manager
+        if not manager:
+            return ToolResult(result_for_model="Error: team manager unavailable", is_error=True)
+        try:
+            agent_id = await manager.add_teammate(
+                tool_input["team_id"],
+                role=TeammateRole(tool_input.get("role", "worker")),
+                prompt=tool_input["prompt"],
+                name=tool_input.get("name"),
+                model_profile=tool_input.get("model_profile"),
+            )
+            return ToolResult(
+                data={"agent_id": agent_id},
+                result_for_model=f"Teammate spawned: {agent_id}",
+            )
+        except (ValueError, RuntimeError) as exc:
+            return ToolResult(result_for_model=f"Error: {exc}", is_error=True)
+
+
+class TeamMessageTool(Tool):
+    name = "TeamMessage"
+    description = "Send a message to a specific teammate in your team."
+    is_read_only = False
+    is_concurrency_safe = True
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "team_id": {"type": "string", "description": "Your team ID."},
+            "to": {"type": "string", "description": "Agent ID of the recipient."},
+            "text": {"type": "string", "minLength": 1, "description": "Message content."},
+        },
+        "required": ["team_id", "to", "text"],
+    }
+
+    async def call(self, tool_input: dict[str, Any], context: ToolContext) -> ToolResult:
+        manager = context.team_manager
+        if not manager:
+            return ToolResult(result_for_model="Error: team manager unavailable", is_error=True)
+        from_agent = context.agent_id or ""
+        msg = await manager.send_message(
+            tool_input["team_id"],
+            from_agent=from_agent,
+            to_agent=tool_input["to"],
+            text=tool_input["text"],
+        )
+        if msg is None:
+            return ToolResult(result_for_model="Error: message delivery failed", is_error=True)
+        return ToolResult(
+            data={"message_id": msg.id, "delivered": True},
+            result_for_model=f"Message delivered to {tool_input['to'][:8]}",
+        )
+
+
+class TeamBroadcastTool(Tool):
+    name = "TeamBroadcast"
+    description = "Broadcast a message to all teammates in your team (except yourself)."
+    is_read_only = False
+    is_concurrency_safe = True
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "team_id": {"type": "string", "description": "Your team ID."},
+            "text": {"type": "string", "minLength": 1, "description": "Message content."},
+        },
+        "required": ["team_id", "text"],
+    }
+
+    async def call(self, tool_input: dict[str, Any], context: ToolContext) -> ToolResult:
+        manager = context.team_manager
+        if not manager:
+            return ToolResult(result_for_model="Error: team manager unavailable", is_error=True)
+        from_agent = context.agent_id or ""
+        messages = await manager.broadcast(
+            tool_input["team_id"],
+            from_agent=from_agent,
+            text=tool_input["text"],
+        )
+        return ToolResult(
+            data={"recipient_count": len(messages)},
+            result_for_model=f"Broadcast delivered to {len(messages)} teammate(s)",
+        )
+
+
+class TeamStatusTool(Tool):
+    name = "TeamStatus"
+    description = "View team status, teammate states, and task board summary."
+    is_read_only = True
+    is_concurrency_safe = True
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "team_id": {"type": "string", "description": "Team ID to inspect."},
+        },
+        "required": ["team_id"],
+    }
+
+    async def call(self, tool_input: dict[str, Any], context: ToolContext) -> ToolResult:
+        manager = context.team_manager
+        if not manager:
+            return ToolResult(result_for_model="Error: team manager unavailable", is_error=True)
+        status = manager.get_team_status(tool_input["team_id"])
+        if not status:
+            return ToolResult(result_for_model=f"Error: team '{tool_input['team_id']}' not found", is_error=True)
+
+        lines = [
+            f"Team: {status['team_id']}  State: {status['state']}",
+            f"Teammates: {status['teammate_count']}/{status['max_teammates']}",
+        ]
+        for t in status["teammates"]:
+            name = t.get("name") or t["agent_id"][:8]
+            lines.append(f"  {name} · {t['role']} · {t['state']}")
+        tasks = status["tasks"]
+        lines.append(
+            f"Tasks: {tasks['total']} total "
+            f"({tasks['pending']} pending, {tasks['claimed']} claimed, "
+            f"{tasks['completed']} done, {tasks['failed']} failed)"
+        )
+        return ToolResult(data=status, result_for_model="\n".join(lines))
+
+
+class TeamTaskAddTool(Tool):
+    name = "TeamTaskAdd"
+    description = "Add a task to the team's shared task board."
+    is_read_only = False
+    is_concurrency_safe = True
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "team_id": {"type": "string", "description": "Team ID."},
+            "description": {"type": "string", "minLength": 1, "description": "Task description."},
+        },
+        "required": ["team_id", "description"],
+    }
+
+    async def call(self, tool_input: dict[str, Any], context: ToolContext) -> ToolResult:
+        manager = context.team_manager
+        if not manager:
+            return ToolResult(result_for_model="Error: team manager unavailable", is_error=True)
+        try:
+            task_id = await manager.add_task(tool_input["team_id"], tool_input["description"])
+            return ToolResult(
+                data={"task_id": task_id},
+                result_for_model=f"Task added: {task_id}",
+            )
+        except ValueError as exc:
+            return ToolResult(result_for_model=f"Error: {exc}", is_error=True)
+
+
+class TeamTaskClaimTool(Tool):
+    name = "TeamTaskClaim"
+    description = "Claim a pending task from the team's task board. Only one agent can claim each task."
+    is_read_only = False
+    is_concurrency_safe = True
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "team_id": {"type": "string", "description": "Team ID."},
+            "task_id": {"type": "string", "description": "Task ID to claim."},
+        },
+        "required": ["team_id", "task_id"],
+    }
+
+    async def call(self, tool_input: dict[str, Any], context: ToolContext) -> ToolResult:
+        manager = context.team_manager
+        if not manager:
+            return ToolResult(result_for_model="Error: team manager unavailable", is_error=True)
+        agent_id = context.agent_id or ""
+        claimed = await manager.claim_task(tool_input["team_id"], tool_input["task_id"], agent_id)
+        if not claimed:
+            return ToolResult(
+                result_for_model="Error: task not found or already claimed",
+                is_error=True,
+            )
+        return ToolResult(
+            data={"task_id": tool_input["task_id"], "claimed": True},
+            result_for_model=f"Task claimed: {tool_input['task_id'][:8]}",
+        )
+
+
+class TeamTaskCompleteTool(Tool):
+    name = "TeamTaskComplete"
+    description = "Mark a claimed task as completed with a result."
+    is_read_only = False
+    is_concurrency_safe = True
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "team_id": {"type": "string", "description": "Team ID."},
+            "task_id": {"type": "string", "description": "Task ID to complete."},
+            "result": {"type": "string", "description": "Result or summary of the completed task."},
+        },
+        "required": ["team_id", "task_id"],
+    }
+
+    async def call(self, tool_input: dict[str, Any], context: ToolContext) -> ToolResult:
+        manager = context.team_manager
+        if not manager:
+            return ToolResult(result_for_model="Error: team manager unavailable", is_error=True)
+        completed = await manager.complete_task(
+            tool_input["team_id"],
+            tool_input["task_id"],
+            tool_input.get("result", ""),
+            context.agent_id or "",
+        )
+        if not completed:
+            return ToolResult(
+                result_for_model="Error: task not found or not in claimed state",
+                is_error=True,
+            )
+        return ToolResult(
+            data={"task_id": tool_input["task_id"], "completed": True},
+            result_for_model=f"Task completed: {tool_input['task_id'][:8]}",
+        )
+
+
+class TeamShutdownTool(Tool):
+    name = "TeamShutdown"
+    description = "Shut down a team: cancel all teammates and clean up resources."
+    is_read_only = False
+    is_concurrency_safe = True
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "team_id": {"type": "string", "description": "Team ID to shut down."},
+        },
+        "required": ["team_id"],
+    }
+
+    async def call(self, tool_input: dict[str, Any], context: ToolContext) -> ToolResult:
+        manager = context.team_manager
+        if not manager:
+            return ToolResult(result_for_model="Error: team manager unavailable", is_error=True)
+        shutdown = await manager.shutdown_team(tool_input["team_id"])
+        if not shutdown:
+            return ToolResult(result_for_model=f"Error: team '{tool_input['team_id']}' not found", is_error=True)
+        return ToolResult(
+            data={"team_id": tool_input["team_id"], "shutdown": True},
+            result_for_model=f"Team shut down: {tool_input['team_id']}",
+        )