crabcode 0.1.0__py3-none-any.whl

crabcode_core/skills/loader.py

@@ -0,0 +1,147 @@
+"""Skill loading — scans .crabcode/skills/ and .claude/skills/ directories.
+
+Search order (later entries override earlier ones with the same name):
+  1. ~/.claude/skills/<name>/SKILL.md     (user global, Claude Code compat)
+  2. ~/.crabcode/skills/<name>/SKILL.md   (user global, crabcode native)
+  3. .claude/skills/<name>/SKILL.md       (project, walking up to home)
+  4. .crabcode/skills/<name>/SKILL.md     (project, walking up to home, highest priority)
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class SkillDefinition:
+    name: str
+    description: str
+    content: str
+    source_path: str
+    when_to_use: str | None = None
+    paths: list[str] = field(default_factory=list)
+
+
+def _parse_frontmatter(text: str) -> tuple[dict[str, str], str]:
+    """Split YAML frontmatter from Markdown body.
+
+    Returns (frontmatter_dict, body). If no frontmatter block is found,
+    returns ({}, original text).
+    """
+    match = re.match(r"^---\s*\n(.*?)\n---\s*\n?", text, re.DOTALL)
+    if not match:
+        return {}, text
+
+    raw_yaml = match.group(1)
+    body = text[match.end():]
+
+    data: dict[str, str] = {}
+    for line in raw_yaml.splitlines():
+        kv = re.match(r'^([\w][\w_-]*):\s*"?(.*?)"?\s*$', line)
+        if kv:
+            data[kv.group(1)] = kv.group(2)
+
+    return data, body.lstrip("\n")
+
+
+def _load_skill_from_file(skill_file: Path) -> SkillDefinition | None:
+    """Parse a single SKILL.md file and return a SkillDefinition, or None on error."""
+    try:
+        text = skill_file.read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+    fm, body = _parse_frontmatter(text)
+    if not body.strip() and not fm:
+        return None
+
+    # Derive name: prefer frontmatter, fall back to parent dir name
+    name = fm.get("name") or skill_file.parent.name
+    description = fm.get("description", "")
+    when_to_use = fm.get("when_to_use") or None
+
+    raw_paths = fm.get("paths", "")
+    paths = [p.strip() for p in raw_paths.split(",") if p.strip()] if raw_paths else []
+
+    return SkillDefinition(
+        name=name,
+        description=description,
+        content=body.strip(),
+        source_path=str(skill_file),
+        when_to_use=when_to_use,
+        paths=paths,
+    )
+
+
+def _scan_skills_dir(base: Path) -> dict[str, SkillDefinition]:
+    """Scan a skills directory for <skill-name>/SKILL.md entries."""
+    skills: dict[str, SkillDefinition] = {}
+    if not base.is_dir():
+        return skills
+
+    for entry in sorted(base.iterdir()):
+        if not (entry.is_dir() or entry.is_symlink()):
+            continue
+        skill_file = entry / "SKILL.md"
+        if not skill_file.is_file():
+            continue
+        skill = _load_skill_from_file(skill_file)
+        if skill:
+            skills[skill.name] = skill
+
+    return skills
+
+
+def _dirs_up_to_home(cwd: str, config_dir: str) -> list[Path]:
+    """Return skill dirs from home down to cwd for a given config directory name.
+
+    Walking home → cwd means closer (more specific) directories override
+    farther ones when we merge.
+    """
+    home = Path.home()
+    current = Path(cwd).resolve()
+    dirs: list[Path] = []
+
+    path = current
+    while True:
+        # Skip the home directory itself — it's covered by the global scan
+        if path != home:
+            dirs.append(path / config_dir / "skills")
+        if path == home or path.parent == path:
+            break
+        path = path.parent
+
+    # Reverse so home-adjacent dirs come first (lower priority), cwd last (highest)
+    dirs.reverse()
+    return dirs
+
+
+def load_skills(cwd: str) -> list[SkillDefinition]:
+    """Load all skills visible from *cwd*, merged by priority.
+
+    Skills with the same name loaded later override earlier ones.
+    """
+    merged: dict[str, SkillDefinition] = {}
+    home = Path.home()
+
+    # 1. ~/.claude/skills/ — lowest priority (Claude Code global compat)
+    for name, skill in _scan_skills_dir(home / ".claude" / "skills").items():
+        merged[name] = skill
+
+    # 2. ~/.crabcode/skills/ — overrides claude global
+    for name, skill in _scan_skills_dir(home / ".crabcode" / "skills").items():
+        merged[name] = skill
+
+    # 3. Project-level .claude/skills/ dirs (home-adjacent → cwd)
+    for skills_dir in _dirs_up_to_home(cwd, ".claude"):
+        for name, skill in _scan_skills_dir(skills_dir).items():
+            merged[name] = skill
+
+    # 4. Project-level .crabcode/skills/ dirs (highest priority)
+    for skills_dir in _dirs_up_to_home(cwd, ".crabcode"):
+        for name, skill in _scan_skills_dir(skills_dir).items():
+            merged[name] = skill
+
+    return list(merged.values())

crabcode_core/tools/__init__.py

@@ -0,0 +1,29 @@
+"""Tool system - built-in tools and tool registry."""
+
+from crabcode_core.types.tool import Tool, ToolResult, ToolContext
+
+
+def get_default_tools() -> list[Tool]:
+    """Return the default set of built-in tools."""
+    from crabcode_core.tools.bash import BashTool
+    from crabcode_core.tools.file_read import FileReadTool
+    from crabcode_core.tools.file_edit import FileEditTool
+    from crabcode_core.tools.file_write import FileWriteTool
+    from crabcode_core.tools.grep import GrepTool
+    from crabcode_core.tools.glob import GlobTool
+    from crabcode_core.tools.lint import LintTool
+    from crabcode_core.tools.memory import MemoryTool
+
+    return [
+        BashTool(),
+        FileReadTool(),
+        FileEditTool(),
+        FileWriteTool(),
+        GrepTool(),
+        GlobTool(),
+        LintTool(),
+        MemoryTool(),
+    ]
+
+
+__all__ = ["Tool", "ToolResult", "ToolContext", "get_default_tools"]

crabcode_core/tools/agent.py

@@ -0,0 +1,160 @@
+"""AgentTool — spawn sub-agents for parallel/isolated work."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from crabcode_core.types.tool import Tool, ToolContext, ToolResult
+
+
+class AgentTool(Tool):
+    name = "Agent"
+    description = "Spawn a sub-agent for parallel or isolated tasks."
+    is_read_only = False
+    is_concurrency_safe = True
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "prompt": {
+                "type": "string",
+                "description": "The task for the sub-agent to perform.",
+            },
+            "subagent_type": {
+                "type": "string",
+                "description": "Type of agent to spawn (e.g., 'explore', 'generalPurpose').",
+                "enum": ["explore", "generalPurpose"],
+            },
+        },
+        "required": ["prompt"],
+    }
+
+    def __init__(
+        self,
+        api_adapter: Any = None,
+        tools: list[Tool] | None = None,
+        prompt_profile: Any = None,
+        max_turns: int = 10,
+        timeout: int = 300,
+        max_output_chars: int = 12_000,
+        max_display_lines: int = 120,
+    ):
+        self._api_adapter = api_adapter
+        self._sub_tools = tools
+        self._prompt_profile = prompt_profile
+        self._max_turns = max_turns
+        self._timeout = timeout
+        self._max_output_chars = max_output_chars
+        self._max_display_lines = max_display_lines
+
+    async def get_prompt(self, **kwargs: Any) -> str:
+        return (
+            "Launch a sub-agent to handle complex, multi-step tasks "
+            "autonomously. Subagents are valuable for parallelizing "
+            "independent queries or for protecting the main context "
+            "window from excessive results.\n\n"
+            "Available types:\n"
+            "- 'explore': Fast agent for codebase exploration — finding "
+            "files, searching code, answering questions about the codebase.\n"
+            "- 'generalPurpose': For complex multi-step tasks that need "
+            "searching, reading, and executing commands.\n\n"
+            "When to use:\n"
+            "- Broadly exploring the codebase for context on a large task\n"
+            "- Parallelizing independent research queries\n"
+            "- Tasks that may produce large outputs\n\n"
+            "When NOT to use:\n"
+            "- Simple, single-step tasks — just call the tools directly\n"
+            "- Searching for a specific file or class — use Glob or Grep\n\n"
+            "IMPORTANT: Avoid duplicating work that subagents are already "
+            "doing. If you delegate research to a subagent, do not also "
+            "perform the same searches yourself."
+        )
+
+    async def call(
+        self,
+        tool_input: dict[str, Any],
+        context: ToolContext,
+    ) -> ToolResult:
+        prompt = tool_input.get("prompt", "")
+
+        if not prompt:
+            return ToolResult(
+                result_for_model="Error: prompt is required",
+                is_error=True,
+            )
+
+        if not self._api_adapter:
+            return ToolResult(
+                result_for_model="Error: AgentTool requires an API adapter",
+                is_error=True,
+            )
+
+        from crabcode_core.prompts.profile import resolve_agent_prompt
+        from crabcode_core.query.loop import QueryParams, query_loop
+        from crabcode_core.types.message import create_user_message
+
+        sub_messages = [create_user_message(content=prompt)]
+
+        sub_context = ToolContext(
+            cwd=context.cwd,
+            messages=[],
+            session_id=context.session_id,
+            env=context.env,
+        )
+
+        tools = self._sub_tools or []
+        agent_prompt = resolve_agent_prompt(self._prompt_profile)
+
+        params = QueryParams(
+            messages=sub_messages,
+            system_prompt=[agent_prompt],
+            user_context={},
+            system_context={},
+            tools=tools,
+            tool_context=sub_context,
+            api_adapter=self._api_adapter,
+            max_turns=self._max_turns,
+        )
+
+        result_parts: list[str] = []
+
+        async def _collect_results():
+            async for event in query_loop(params):
+                from crabcode_core.types.event import (
+                    ErrorEvent,
+                    StreamTextEvent,
+                    ToolResultEvent,
+                )
+                if isinstance(event, StreamTextEvent):
+                    result_parts.append(event.text)
+                elif isinstance(event, ToolResultEvent):
+                    body = (event.result or "").strip()
+                    if len(body) > self._max_output_chars:
+                        body = body[:self._max_output_chars] + "\n… (truncated)"
+                    result_parts.append(
+                        f"\n\n[Tool {event.tool_name} →]\n{body or '(empty)'}\n"
+                    )
+                elif isinstance(event, ErrorEvent):
+                    result_parts.append(f"\n[Error: {event.message}]")
+
+        try:
+            await asyncio.wait_for(_collect_results(), timeout=self._timeout)
+        except asyncio.TimeoutError:
+            result_parts.append(f"\n[Sub-agent timed out after {self._timeout}s]")
+
+        result = "".join(result_parts)
+        if not result:
+            result = "Sub-agent completed but produced no text output."
+
+        # Build a display-friendly version: keep more content but cap by line count
+        display = result
+        lines = display.split("\n")
+        if len(lines) > self._max_display_lines:
+            kept = "\n".join(lines[:self._max_display_lines])
+            display = kept + f"\n… ({len(lines) - self._max_display_lines} more lines truncated)"
+
+        return ToolResult(
+            data={"agent_output": result},
+            result_for_model=result,
+            result_for_display=display,
+        )

crabcode_core/tools/bash.py

@@ -0,0 +1,127 @@
+"""BashTool — execute shell commands."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Any
+
+from crabcode_core.types.tool import Tool, ToolContext, ToolResult
+
+
+class BashTool(Tool):
+    name = "Bash"
+    description = "Execute a bash command in the shell."
+    is_read_only = False
+    is_concurrency_safe = False
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "command": {
+                "type": "string",
+                "description": "The bash command to execute.",
+            },
+            "timeout": {
+                "type": "integer",
+                "description": "Timeout in seconds (default: 120).",
+            },
+        },
+        "required": ["command"],
+    }
+
+    async def get_prompt(self, **kwargs: Any) -> str:
+        return (
+            "Execute a bash command in the shell. Use for system commands, "
+            "running scripts, git operations, and other terminal tasks. "
+            "Prefer dedicated tools (Read, Edit, Write, Glob, Grep) over "
+            "bash when they can accomplish the task.\n\n"
+            "Commands run in the user's shell with their environment. "
+            "The command is executed in the working directory of the "
+            "current session. The shell is stateful across calls — "
+            "environment variables and directory changes persist.\n\n"
+            "Guidelines:\n"
+            "- Always quote file paths that contain spaces with double "
+            'quotes: cd "/path/with spaces" (correct) vs cd /path/with '
+            "spaces (incorrect, will fail).\n"
+            "- For long-running processes (dev servers, watchers), they "
+            "will be killed when the timeout expires. Warn the user if "
+            "a command is expected to run indefinitely.\n"
+            "- When issuing multiple independent commands, call Bash "
+            "multiple times in parallel rather than chaining with &&.\n"
+            "- If commands depend on each other and must run sequentially, "
+            "chain them with && in a single call.\n"
+            "- Do NOT use interactive commands (e.g., git rebase -i, "
+            "vim, nano) — they require user input that is not supported.\n"
+            "- If a command fails, read the error output carefully before "
+            "retrying. Do not blindly retry the same command."
+        )
+
+    async def call(
+        self,
+        tool_input: dict[str, Any],
+        context: ToolContext,
+    ) -> ToolResult:
+        command = tool_input.get("command", "")
+        timeout = tool_input.get("timeout", 120)
+
+        if not command.strip():
+            return ToolResult(
+                result_for_model="Error: empty command",
+                is_error=True,
+            )
+
+        env = {**os.environ, **context.env}
+
+        try:
+            proc = await asyncio.create_subprocess_shell(
+                command,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                cwd=context.cwd,
+                env=env,
+            )
+
+            try:
+                stdout_bytes, stderr_bytes = await asyncio.wait_for(
+                    proc.communicate(), timeout=timeout
+                )
+            except asyncio.TimeoutError:
+                proc.kill()
+                await proc.wait()
+                return ToolResult(
+                    result_for_model=f"Command timed out after {timeout}s",
+                    is_error=True,
+                )
+
+            stdout = stdout_bytes.decode("utf-8", errors="replace")
+            stderr = stderr_bytes.decode("utf-8", errors="replace")
+            exit_code = proc.returncode or 0
+
+            max_chars = 100_000
+            if len(stdout) > max_chars:
+                stdout = stdout[:max_chars] + "\n... (truncated)"
+            if len(stderr) > max_chars:
+                stderr = stderr[:max_chars] + "\n... (truncated)"
+
+            parts: list[str] = []
+            if stdout:
+                parts.append(stdout)
+            if stderr:
+                parts.append(f"stderr:\n{stderr}")
+            if exit_code != 0:
+                parts.append(f"Exit code: {exit_code}")
+
+            output = "\n".join(parts) if parts else "(no output)"
+
+            return ToolResult(
+                data={"stdout": stdout, "stderr": stderr, "exit_code": exit_code},
+                result_for_model=output,
+                result_for_display=output,
+                is_error=exit_code != 0,
+            )
+
+        except Exception as e:
+            return ToolResult(
+                result_for_model=f"Error executing command: {e}",
+                is_error=True,
+            )

crabcode_core/tools/diff_utils.py

@@ -0,0 +1,120 @@
+"""Diff utilities for file edit/write tools."""
+
+from __future__ import annotations
+
+import difflib
+
+
+def compute_diff(
+    old: str,
+    new: str,
+    filepath: str = "",
+    context_lines: int = 3,
+) -> dict:
+    """Compute a structured diff between old and new file content.
+
+    Returns a dict with:
+      line_range  - (start, end) 1-indexed line range of first change
+      diff_text   - unified diff string (compact, for model)
+      display     - formatted diff string (for terminal display)
+      stats       - {"added": N, "removed": N}
+    """
+    old_lines = old.splitlines(keepends=True)
+    new_lines = new.splitlines(keepends=True)
+
+    diff_lines = list(difflib.unified_diff(
+        old_lines,
+        new_lines,
+        fromfile=filepath,
+        tofile=filepath,
+        lineterm="",
+        n=context_lines,
+    ))
+
+    if not diff_lines:
+        return {
+            "line_range": None,
+            "diff_text": "",
+            "display": "",
+            "stats": {"added": 0, "removed": 0},
+        }
+
+    added = sum(1 for l in diff_lines if l.startswith("+") and not l.startswith("+++"))
+    removed = sum(1 for l in diff_lines if l.startswith("-") and not l.startswith("---"))
+
+    first_change_line = _find_first_change_line(old_lines, new_lines)
+    last_change_line = _find_last_change_line(old_lines, new_lines)
+
+    diff_text = "\n".join(diff_lines)
+
+    max_diff_chars = 10_000
+    if len(diff_text) > max_diff_chars:
+        diff_text = diff_text[:max_diff_chars] + "\n... (diff truncated)"
+
+    return {
+        "line_range": (first_change_line, last_change_line),
+        "diff_text": diff_text,
+        "display": diff_text,
+        "stats": {"added": added, "removed": removed},
+    }
+
+
+def _find_first_change_line(old: list[str], new: list[str]) -> int:
+    """Find the 1-indexed line number of the first difference."""
+    for i, (a, b) in enumerate(zip(old, new)):
+        if a != b:
+            return i + 1
+    return min(len(old), len(new)) + 1
+
+
+def _find_last_change_line(old: list[str], new: list[str]) -> int:
+    """Find the 1-indexed line number (in new file) of the last difference."""
+    old_rev = list(reversed(old))
+    new_rev = list(reversed(new))
+    tail_common = 0
+    for a, b in zip(old_rev, new_rev):
+        if a != b:
+            break
+        tail_common += 1
+    return max(1, len(new) - tail_common)
+
+
+def format_edit_summary(
+    filepath: str,
+    diff_info: dict,
+    replacements: int = 1,
+) -> tuple[str, str]:
+    """Format diff info into (result_for_model, result_for_display).
+
+    Returns a pair of strings optimized for model consumption and
+    terminal display respectively.
+    """
+    lr = diff_info["line_range"]
+    stats = diff_info["stats"]
+
+    if lr:
+        line_desc = f"lines {lr[0]}-{lr[1]}" if lr[0] != lr[1] else f"line {lr[0]}"
+    else:
+        line_desc = ""
+
+    stat_parts = []
+    if stats["added"]:
+        stat_parts.append(f"+{stats['added']}")
+    if stats["removed"]:
+        stat_parts.append(f"-{stats['removed']}")
+    stat_str = ", ".join(stat_parts)
+
+    model_msg = f"Updated {filepath}"
+    if line_desc:
+        model_msg += f" ({line_desc})"
+    if stat_str:
+        model_msg += f" [{stat_str}]"
+    if replacements > 1:
+        model_msg += f" ({replacements} replacements)"
+
+    display_parts = [model_msg]
+    if diff_info["display"]:
+        display_parts.append(diff_info["display"])
+    display_msg = "\n".join(display_parts)
+
+    return model_msg, display_msg