crabcode 0.1.0__py3-none-any.whl

crabcode_core/tools/skill.py

@@ -0,0 +1,112 @@
+"""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:
+                lines.append(f"### {skill.name}")
+                if skill.description:
+                    lines.append(f"Description: {skill.description}")
+                if skill.when_to_use:
+                    lines.append(f"When to use: {skill.when_to_use}")
+                lines.append("")
+
+        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/types/__init__.py

@@ -0,0 +1,73 @@
+"""Core type definitions for CrabCode."""
+
+from crabcode_core.types.message import (
+    AssistantMessage,
+    ContentBlock,
+    Message,
+    MessageRole,
+    SystemMessage,
+    TextBlock,
+    ThinkingBlock,
+    ToolResultBlock,
+    ToolUseBlock,
+    UserMessage,
+)
+from crabcode_core.types.tool import (
+    PermissionBehavior,
+    PermissionResult,
+    Tool,
+    ToolContext,
+    ToolResult,
+)
+from crabcode_core.types.event import (
+    CompactEvent,
+    CoreEvent,
+    ErrorEvent,
+    PermissionRequestEvent,
+    PermissionResponseEvent,
+    StreamTextEvent,
+    ThinkingEvent,
+    ToolResultEvent,
+    ToolUseEvent,
+    TurnCompleteEvent,
+)
+from crabcode_core.types.config import (
+    ApiConfig,
+    CrabCodeSettings,
+    McpServerConfig,
+    PermissionRule,
+    PermissionsSettings,
+)
+
+__all__ = [
+    "AssistantMessage",
+    "ContentBlock",
+    "Message",
+    "MessageRole",
+    "SystemMessage",
+    "TextBlock",
+    "ThinkingBlock",
+    "ToolResultBlock",
+    "ToolUseBlock",
+    "UserMessage",
+    "PermissionBehavior",
+    "PermissionResult",
+    "Tool",
+    "ToolContext",
+    "ToolResult",
+    "CompactEvent",
+    "CoreEvent",
+    "ErrorEvent",
+    "PermissionRequestEvent",
+    "PermissionResponseEvent",
+    "StreamTextEvent",
+    "ThinkingEvent",
+    "ToolResultEvent",
+    "ToolUseEvent",
+    "TurnCompleteEvent",
+    "ApiConfig",
+    "CrabCodeSettings",
+    "McpServerConfig",
+    "PermissionRule",
+    "PermissionsSettings",
+]

crabcode_core/types/config.py

@@ -0,0 +1,103 @@
+"""Configuration types for CrabCode settings."""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+class PermissionRule(BaseModel):
+    """A single permission rule for tool access control."""
+    tool: str
+    path: str | None = None
+    command: str | None = None
+
+
+class PermissionsSettings(BaseModel):
+    allow: list[PermissionRule] = Field(default_factory=list)
+    deny: list[PermissionRule] = Field(default_factory=list)
+    ask: list[PermissionRule] = Field(default_factory=list)
+    default_mode: str | None = None
+    additional_directories: list[str] = Field(default_factory=list)
+    run_everything: bool = False
+
+
+class McpServerConfig(BaseModel):
+    command: list[str] | None = None
+    url: str | None = None
+    env: dict[str, str] = Field(default_factory=dict)
+    disabled: bool = False
+
+
+class ApiConfig(BaseModel):
+    """API backend configuration."""
+    provider: str | None = None  # anthropic | openai | codex | bedrock | vertex | router
+    model: str | None = None
+    base_url: str | None = None
+    api_key_env: str | None = None
+    format: str | None = None  # anthropic | openai | codex (for routers)
+    max_tokens: int = 16384
+    thinking_enabled: bool = True
+    thinking_budget: int = 10000
+    timeout: int = 300  # seconds, for API calls
+
+
+class AgentSettings(BaseModel):
+    """Settings for the built-in Agent (sub-agent) tool."""
+    max_turns: int = 10
+    timeout: int = 300
+    max_output_chars: int = 12000
+
+
+class DisplaySettings(BaseModel):
+    """Settings for tool result display in the terminal."""
+    default_max_lines: int = 50
+    tool_max_lines: dict[str, int] = {}
+    max_chars: int = 50_000
+
+    # Built-in defaults merged under tool_max_lines overrides
+    _TOOL_DEFAULTS: dict[str, int] = {
+        "Agent": 120,
+        "Bash": 60,
+        "Grep": 50,
+        "Glob": 30,
+        "Read": 80,
+        "Lint": 60,
+        "CodebaseSearch": 50,
+    }
+
+    def get_max_lines(self, tool_name: str) -> int:
+        """Return max display lines for a tool, considering overrides."""
+        if tool_name in self.tool_max_lines:
+            return self.tool_max_lines[tool_name]
+        return self._TOOL_DEFAULTS.get(tool_name, self.default_max_lines)
+
+
+class CrabCodeSettings(BaseModel):
+    """Full settings.json schema."""
+    permissions: PermissionsSettings = Field(default_factory=PermissionsSettings)
+    env: dict[str, str] = Field(default_factory=dict)
+    mcp_servers: dict[str, McpServerConfig] = Field(default_factory=dict)
+    api: ApiConfig = Field(default_factory=ApiConfig)
+    models: dict[str, ApiConfig] = Field(default_factory=dict)
+    default_model: str | None = None
+    hooks: dict[str, list[dict[str, Any]]] = Field(default_factory=dict)
+    auto_compact_enabled: bool = True
+    max_context_length: int | None = None
+    language: str | None = None
+    output_style: str | None = None
+    prompt_profile: dict[str, Any] | None = None
+    extra_tools: list[str] = Field(default_factory=list)
+    tool_settings: dict[str, dict[str, Any]] = Field(default_factory=dict)
+    agent: AgentSettings = Field(default_factory=AgentSettings)
+    display: DisplaySettings = Field(default_factory=DisplaySettings)
+
+    model_config = {"extra": "allow"}
+
+    def get_api_config(self, model_name: str | None = None) -> ApiConfig:
+        """Return the ApiConfig for a named model, falling back to the default api config."""
+        name = model_name or self.default_model
+        if name and name in self.models:
+            return self.models[name]
+        return self.api

crabcode_core/types/event.py

@@ -0,0 +1,105 @@
+"""Event types for Core <-> Frontend communication.
+
+The Core emits these events as an async stream. Frontends (CLI, Web UI, SDK)
+consume them to render output, handle permission prompts, etc.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Union
+
+
+@dataclass
+class StreamTextEvent:
+    """A chunk of streamed text from the model."""
+    text: str
+
+
+@dataclass
+class ThinkingEvent:
+    """A chunk of thinking/reasoning from the model."""
+    text: str
+
+
+@dataclass
+class ToolUseEvent:
+    """The model wants to use a tool."""
+    tool_name: str
+    tool_input: dict[str, Any]
+    tool_use_id: str
+
+
+@dataclass
+class ToolResultEvent:
+    """Result from a tool execution."""
+    tool_use_id: str
+    tool_name: str
+    result: str
+    is_error: bool = False
+    result_for_display: str | None = None
+
+
+@dataclass
+class PermissionRequestEvent:
+    """Core is requesting permission from the frontend to use a tool."""
+    tool_name: str
+    tool_input: dict[str, Any]
+    tool_use_id: str
+
+
+@dataclass
+class PermissionResponseEvent:
+    """Frontend's response to a permission request."""
+    tool_use_id: str
+    allowed: bool
+    always_allow: bool = False
+
+
+@dataclass
+class CompactEvent:
+    """Conversation was compacted."""
+    summary: str
+    messages_before: int = 0
+    messages_after: int = 0
+
+
+@dataclass
+class ErrorEvent:
+    """An error occurred."""
+    message: str
+    recoverable: bool = True
+    error_type: str = ""
+
+
+@dataclass
+class TurnCompleteEvent:
+    """An agentic turn completed."""
+    reason: str = "end_turn"
+    turn_count: int = 0
+    usage: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class StreamModeEvent:
+    """Signals a phase transition in the streaming lifecycle.
+
+    Modes:
+      - "requesting": API request sent, waiting for first chunk
+      - "thinking": model entered extended thinking
+      - "responding": model is streaming text output
+    """
+    mode: str
+
+
+CoreEvent = Union[
+    StreamTextEvent,
+    ThinkingEvent,
+    ToolUseEvent,
+    ToolResultEvent,
+    PermissionRequestEvent,
+    CompactEvent,
+    ErrorEvent,
+    TurnCompleteEvent,
+    StreamModeEvent,
+]

crabcode_core/types/message.py

@@ -0,0 +1,177 @@
+"""Message types for the CrabCode conversation protocol.
+
+Internal format follows Anthropic's message structure. API adapters
+translate to/from provider-specific formats.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Literal, Union
+
+from pydantic import BaseModel, Field
+
+
+class MessageRole(str, Enum):
+    USER = "user"
+    ASSISTANT = "assistant"
+    SYSTEM = "system"
+
+
+# --- Content blocks ---
+
+
+class TextBlock(BaseModel):
+    type: Literal["text"] = "text"
+    text: str
+
+
+class ToolUseBlock(BaseModel):
+    type: Literal["tool_use"] = "tool_use"
+    id: str
+    name: str
+    input: dict[str, Any]
+
+
+class ToolResultBlock(BaseModel):
+    type: Literal["tool_result"] = "tool_result"
+    tool_use_id: str
+    content: str
+    is_error: bool = False
+
+
+class ThinkingBlock(BaseModel):
+    type: Literal["thinking"] = "thinking"
+    thinking: str
+
+
+class SignatureBlock(BaseModel):
+    type: Literal["signature"] = "signature"
+    signature: str
+
+
+ContentBlock = Union[TextBlock, ToolUseBlock, ToolResultBlock, ThinkingBlock, SignatureBlock]
+
+
+# --- Messages ---
+
+
+class Message(BaseModel):
+    """Base message in a conversation."""
+
+    uuid: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    parent_uuid: str | None = None
+    role: MessageRole
+    content: list[ContentBlock] | str
+    timestamp: str = Field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat()
+    )
+    is_compact_summary: bool = False
+
+    @property
+    def text_content(self) -> str:
+        """Extract plain text from content blocks."""
+        if isinstance(self.content, str):
+            return self.content
+        parts: list[str] = []
+        for block in self.content:
+            if isinstance(block, TextBlock):
+                parts.append(block.text)
+        return "".join(parts)
+
+    @property
+    def tool_use_blocks(self) -> list[ToolUseBlock]:
+        if isinstance(self.content, str):
+            return []
+        return [b for b in self.content if isinstance(b, ToolUseBlock)]
+
+    @property
+    def has_tool_use(self) -> bool:
+        return len(self.tool_use_blocks) > 0
+
+
+class UserMessage(Message):
+    role: Literal[MessageRole.USER] = MessageRole.USER
+    tool_use_result: str | None = None
+    source_tool_assistant_uuid: str | None = None
+
+
+class AssistantMessage(Message):
+    role: Literal[MessageRole.ASSISTANT] = MessageRole.ASSISTANT
+    api_error: str | None = None
+    usage: dict[str, Any] | None = None
+    request_id: str | None = None
+
+
+class SystemMessage(Message):
+    role: Literal[MessageRole.SYSTEM] = MessageRole.SYSTEM
+
+
+def create_user_message(
+    content: list[ContentBlock] | str,
+    **kwargs: Any,
+) -> UserMessage:
+    return UserMessage(content=content, **kwargs)
+
+
+def create_assistant_message(
+    content: list[ContentBlock] | str,
+    **kwargs: Any,
+) -> AssistantMessage:
+    return AssistantMessage(content=content, **kwargs)
+
+
+def create_tool_result_message(
+    tool_use_id: str,
+    result: str,
+    is_error: bool = False,
+    source_tool_assistant_uuid: str | None = None,
+) -> UserMessage:
+    """Create a user message containing a tool result."""
+    return UserMessage(
+        content=[
+            ToolResultBlock(
+                tool_use_id=tool_use_id,
+                content=result,
+                is_error=is_error,
+            )
+        ],
+        parent_uuid=source_tool_assistant_uuid,
+        tool_use_result=result,
+        source_tool_assistant_uuid=source_tool_assistant_uuid,
+    )
+
+
+def deserialize_content(raw: Any) -> list[ContentBlock] | str:
+    """Deserialize raw JSON content back into typed ContentBlock list."""
+    if isinstance(raw, str):
+        return raw
+    if not isinstance(raw, list):
+        return str(raw) if raw else ""
+
+    _BLOCK_MAP: dict[str, type[BaseModel]] = {
+        "text": TextBlock,
+        "tool_use": ToolUseBlock,
+        "tool_result": ToolResultBlock,
+        "thinking": ThinkingBlock,
+        "signature": SignatureBlock,
+    }
+
+    blocks: list[ContentBlock] = []
+    for item in raw:
+        if not isinstance(item, dict):
+            continue
+        block_type = item.get("type", "")
+        cls = _BLOCK_MAP.get(block_type)
+        if cls:
+            try:
+                blocks.append(cls.model_validate(item))
+            except Exception:
+                if "text" in item:
+                    blocks.append(TextBlock(text=item["text"]))
+        elif "text" in item:
+            blocks.append(TextBlock(text=item["text"]))
+
+    return blocks if blocks else ""

crabcode_core/types/tool.py

@@ -0,0 +1,138 @@
+"""Tool system types for CrabCode."""
+
+from __future__ import annotations
+
+import asyncio
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING, Any, Callable, Coroutine
+
+if TYPE_CHECKING:
+    from crabcode_core.types.message import AssistantMessage, Message
+
+
+class PermissionBehavior(str, Enum):
+    ALLOW = "allow"
+    DENY = "deny"
+    ASK = "ask"
+
+
+ToolEventCallback = Callable[[str, str, dict[str, Any]], None]
+"""Signature: (tool_name, event_type, data)"""
+
+
+@dataclass
+class PermissionResult:
+    behavior: PermissionBehavior = PermissionBehavior.ALLOW
+    reason: str | None = None
+    updated_input: dict[str, Any] | None = None
+
+
+@dataclass
+class ToolResult:
+    """Result from executing a tool."""
+
+    data: Any = None
+    result_for_model: str = ""
+    result_for_display: str | None = None
+    is_error: bool = False
+
+
+@dataclass
+class ToolContext:
+    """Context passed to tool execution."""
+
+    cwd: str = "."
+    messages: list[Message] = field(default_factory=list)
+    abort_signal: Any | None = None
+    session_id: str = ""
+    env: dict[str, str] = field(default_factory=dict)
+    on_event: ToolEventCallback | None = None
+    tool_config: dict[str, Any] = field(default_factory=dict)
+
+
+CanUseToolFn = Callable[
+    ["Tool", dict[str, Any], "ToolContext"],
+    Coroutine[Any, Any, PermissionResult],
+]
+
+
+class Tool(ABC):
+    """Base class for all CrabCode tools."""
+
+    name: str = ""
+    description: str = ""
+    input_schema: dict[str, Any] = {}
+    is_read_only: bool = False
+    is_concurrency_safe: bool = False
+    is_enabled: bool = True
+
+    _cached_prompt: str | None = None
+    _background_task: asyncio.Task[Any] | None = None
+    _setup_context: ToolContext | None = None
+
+    @abstractmethod
+    async def call(
+        self,
+        tool_input: dict[str, Any],
+        context: ToolContext,
+    ) -> ToolResult:
+        """Execute the tool with given input."""
+        ...
+
+    async def setup(self, context: ToolContext) -> None:
+        """Called once during session init. Override for heavy initialization."""
+        self._setup_context = context
+
+    def emit_event(self, event_type: str, data: dict[str, Any] | None = None) -> None:
+        """Emit a tool event (progress, ready, error, etc.)."""
+        if self._setup_context and self._setup_context.on_event:
+            self._setup_context.on_event(self.name, event_type, data or {})
+
+    async def wait_ready(self) -> None:
+        """Wait for background initialization to complete."""
+        if self._background_task and not self._background_task.done():
+            await self._background_task
+
+    async def get_prompt(self, **kwargs: Any) -> str:
+        """Return the tool description for the system prompt / API tools list."""
+        return self.description
+
+    async def validate_input(
+        self, tool_input: dict[str, Any]
+    ) -> str | None:
+        """Validate input. Return error string or None if valid."""
+        return None
+
+    async def check_permissions(
+        self,
+        tool_input: dict[str, Any],
+        context: ToolContext,
+    ) -> PermissionResult:
+        """Check if the tool can be used with the given input."""
+        return PermissionResult()
+
+    def to_api_schema(self) -> dict[str, Any]:
+        """Convert to API tool schema for model requests.
+
+        Uses the detailed prompt from get_prompt() when available,
+        falling back to the short description.
+        """
+        return {
+            "name": self.name,
+            "description": self._cached_prompt or self.description,
+            "input_schema": self.input_schema,
+        }
+
+    async def resolve_prompt(self, **kwargs: Any) -> None:
+        """Pre-resolve the detailed prompt for use in to_api_schema().
+
+        Call this once during setup so to_api_schema() can include the
+        full tool description without being async.
+        """
+        prompt = await self.get_prompt(**kwargs)
+        if prompt and prompt != self.description:
+            self._cached_prompt = prompt
+        else:
+            self._cached_prompt = None