crabcode 0.1.6__py3-none-win_amd64.whl

crabcode_core/types/event.py

@@ -0,0 +1,334 @@
+"""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 TYPE_CHECKING, Any, Union
+
+if TYPE_CHECKING:
+    from crabcode_core.types.message import Message
+
+
+@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
+    agent_id: str | None = None
+
+
+@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
+    tool_input: dict[str, Any] = field(default_factory=dict)
+    agent_id: str | None = None
+    images: list[dict[str, str]] = field(default_factory=list)
+
+
+@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
+    reason: str | None = None
+    permission_key: str | None = None
+    agent_id: str | None = None
+    request_kind: str = "tool"
+
+
+@dataclass
+class PermissionResponseEvent:
+    """Frontend's response to a permission request."""
+    tool_use_id: str
+    allowed: bool
+    always_allow: bool = False
+    agent_id: str | None = None
+    feedback: str | None = None
+
+
+@dataclass
+class CompactEvent:
+    """Conversation was compacted."""
+    summary: str
+    messages_before: int = 0
+    messages_after: int = 0
+    trigger: str = "auto"
+    agent_id: str | None = None
+    # Internal frozen snapshots used by CoreSession for ordered persistence.
+    # Frontend payload converters intentionally expose only the fields above.
+    source_messages: list[Message] | None = field(default=None, repr=False)
+    checkpoint_messages: list[Message] | None = field(default=None, repr=False)
+
+
+@dataclass
+class ErrorEvent:
+    """An error occurred."""
+    message: str
+    recoverable: bool = True
+    error_type: str = ""
+    agent_id: str | None = None
+
+
+@dataclass
+class TurnCompleteEvent:
+    """An agentic turn completed."""
+    reason: str = "end_turn"
+    turn_count: int = 0
+    usage: dict[str, Any] = field(default_factory=dict)
+    context_used_tokens: int = 0
+    context_window_tokens: int = 0
+    context_remaining_tokens: int = 0
+    context_used_percent: float = 0.0
+    context_token_source: str = "estimated"
+    assistant_message_uuid: str | None = None
+    turn_details: dict[str, Any] | None = None
+    prompt_budget: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ChoiceRequestEvent:
+    """Core is requesting the user to make a choice from a list of options."""
+    tool_use_id: str
+    question: str
+    options: list[str]
+    multiple: bool = False
+    agent_id: str | None = None
+
+
+@dataclass
+class ChoiceResponseEvent:
+    """Frontend's response to a choice request."""
+    tool_use_id: str
+    selected: list[str]
+    cancelled: bool = False
+    agent_id: str | None = None
+
+
+@dataclass
+class StreamModeEvent:
+    """Signals a phase transition in the streaming lifecycle.
+
+    Modes:
+      - "requesting": API request sent, waiting for first chunk
+      - "compacting": conversation checkpoint generation is in progress
+      - "thinking": model entered extended thinking
+      - "responding": model is streaming text output
+    """
+    mode: str
+    agent_id: str | None = None
+
+
+@dataclass
+class StreamRetryEvent:
+    """A retryable model stream failure that has scheduled a reconnect."""
+    message: str
+    error: str
+    retry_count: int
+    max_retries: int
+    delay_seconds: float
+    unbounded: bool = False
+    transport_fallback: bool = False
+    discarded_text_chars: int = 0
+    agent_id: str | None = None
+
+
+@dataclass
+class SteeringAppliedEvent:
+    """Queued user guidance entered the conversation at a safe boundary."""
+    count: int = 1
+
+
+@dataclass
+class QueuedMessageStartedEvent:
+    """A queued follow-up is starting a separate user turn."""
+    text: str
+    images: list[dict[str, Any]] = field(default_factory=list)
+    request_id: str | None = None
+
+
+@dataclass
+class QueuedMessageUpdatedEvent:
+    """A pending follow-up was recalled, deleted, or promoted to guidance."""
+    request_id: str
+    action: str
+
+
+@dataclass
+class AgentStateEvent:
+    """Lifecycle update for a managed sub-agent."""
+    agent_id: str
+    parent_agent_id: str | None
+    status: str
+    subagent_type: str
+    title: str
+    message: str = ""
+    usage: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class AgentOutputEvent:
+    """Streamed output or tool activity from a managed sub-agent."""
+    agent_id: str
+    stream: str
+    text: str
+    tool_name: str | None = None
+
+
+@dataclass
+class ModeChangeEvent:
+    """Agent mode has changed (e.g. plan <-> agent)."""
+    mode: str  # "plan" | "agent"
+    reason: str = ""
+
+
+@dataclass
+class PlanReadyEvent:
+    """A structured execution plan has been produced by plan mode."""
+    plan: dict[str, Any]
+
+
+@dataclass
+class TeamMessageEvent:
+    """A message was sent between teammates."""
+    team_id: str
+    from_agent: str
+    to_agent: str
+    text: str
+    msg_type: str = "text"
+    message_id: str = ""
+
+
+@dataclass
+class PeerMessageEvent:
+    """A message arrived from an independent CrabCode session."""
+    message_id: str
+    from_session_id: str
+    from_name: str
+    from_cwd: str
+    text: str
+
+
+@dataclass
+class TeamStateEvent:
+    """A teammate's state changed within a team."""
+    team_id: str
+    agent_id: str
+    old_state: str
+    new_state: str
+    role: str = ""
+
+
+@dataclass
+class TaskUpdateEvent:
+    """A task on the shared task board was updated."""
+    team_id: str
+    task_id: str
+    status: str
+    assignee: str | None = None
+    description: str = ""
+
+
+@dataclass
+class SnapshotEvent:
+    """A file system snapshot was created."""
+    snapshot_id: str
+    tool_name: str
+    files: list[str]  # files affected
+
+
+@dataclass
+class RevertEvent:
+    """File system state was reverted."""
+    snapshot_id: str
+    files_restored: list[str]
+
+
+@dataclass
+class ScheduleRunEvent:
+    """A scheduled job has been executed (or failed/timed out)."""
+    job_id: str
+    run_id: str
+    status: str  # "success" | "failed" | "timeout"
+    duration_seconds: float = 0.0
+    error_message: str = ""
+    result_summary: str = ""
+    next_run: str | None = None
+
+
+@dataclass
+class DocumentJobEvent:
+    """Progress for a structured document translation or Blog operation."""
+    action: str
+    status: str
+    locale: str = ""
+    language: str = ""
+    source: str = ""
+    current: int = 0
+    total: int = 0
+    message: str = ""
+    engine: str = "legacy"
+
+
+@dataclass
+class DocumentSelectionTranslationEvent:
+    """Translation result for a user-selected document excerpt."""
+    operation_id: str
+    locale: str
+    source_text: str
+    translated_text: str = ""
+    status: str = "completed"
+    message: str = ""
+
+
+CoreEvent = Union[
+    StreamTextEvent,
+    ThinkingEvent,
+    ToolUseEvent,
+    ToolResultEvent,
+    PermissionRequestEvent,
+    ChoiceRequestEvent,
+    CompactEvent,
+    ErrorEvent,
+    TurnCompleteEvent,
+    StreamModeEvent,
+    StreamRetryEvent,
+    SteeringAppliedEvent,
+    QueuedMessageStartedEvent,
+    QueuedMessageUpdatedEvent,
+    AgentStateEvent,
+    AgentOutputEvent,
+    ModeChangeEvent,
+    PlanReadyEvent,
+    PeerMessageEvent,
+    TeamMessageEvent,
+    TeamStateEvent,
+    TaskUpdateEvent,
+    SnapshotEvent,
+    RevertEvent,
+    ScheduleRunEvent,
+    DocumentJobEvent,
+    DocumentSelectionTranslationEvent,
+]

crabcode_core/types/message.py

@@ -0,0 +1,263 @@
+"""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
+from crabcode_core.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
+
+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
+
+
+class ImageBlock(BaseModel):
+    """An image content block (base64-encoded).
+
+    Follows Anthropic's image block format. API adapters translate
+    to provider-specific representations.
+    """
+    type: Literal["image"] = "image"
+    source: dict[str, Any]  # {"type": "base64", "media_type": "image/png", "data": "..."}
+    # Persist UI captions outside source so provider image payloads stay valid.
+    description: str = ""
+
+
+ContentBlock = Union[TextBlock, ToolUseBlock, ToolResultBlock, ThinkingBlock, SignatureBlock, ImageBlock]
+
+
+# --- 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
+    origin: str | None = None
+
+    @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
+    reply_to_uuid: str | None = None
+    api_error: str | None = None
+    usage: dict[str, Any] | None = None
+    request_id: str | None = None
+    turn_details: dict[str, Any] | 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,
+    images: list[dict[str, 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,
+            )
+        ] + [
+            ImageBlock(
+                source={
+                    "type": "base64",
+                    "media_type": image.get("media_type", "image/png"),
+                    "data": image.get("data", ""),
+                },
+                description=image.get("description", ""),
+            )
+            for image in (images or [])
+            if image.get("data")
+        ],
+        parent_uuid=source_tool_assistant_uuid,
+        tool_use_result=result,
+        source_tool_assistant_uuid=source_tool_assistant_uuid,
+    )
+
+
+def message_from_entry(raw: dict[str, Any]) -> Message | None:
+    """Rebuild a durable message entry without dropping subtype metadata."""
+    role = raw.get("type")
+    model: type[Message]
+    if role == MessageRole.USER.value:
+        model = UserMessage
+    elif role == MessageRole.ASSISTANT.value:
+        model = AssistantMessage
+    elif role == MessageRole.SYSTEM.value:
+        model = SystemMessage
+    else:
+        return None
+
+    payload = dict(raw)
+    payload.pop("type", None)
+    payload["role"] = role
+    payload["content"] = deserialize_content(payload.get("content", ""))
+    try:
+        return model.model_validate(payload)
+    except Exception:
+        logger.warning("Failed to restore durable %s message", role, exc_info=True)
+        return None
+
+
+def find_assistant_reply(
+    messages: list[Message],
+    message_id: str,
+) -> AssistantMessage | None:
+    """Find a successful final assistant reply correlated to one input message."""
+    related_uuids = {message_id}
+    message_seen = False
+    for message in messages:
+        if message.uuid == message_id:
+            message_seen = True
+            continue
+
+        directly_related = (
+            isinstance(message, AssistantMessage)
+            and message.reply_to_uuid == message_id
+        )
+        ancestrally_related = message_seen and message.parent_uuid in related_uuids
+        if not directly_related and not ancestrally_related:
+            continue
+
+        related_uuids.add(message.uuid)
+        if (
+            isinstance(message, AssistantMessage)
+            and not message.api_error
+            and not message.has_tool_use
+        ):
+            return message
+    return None
+
+
+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,
+        "image": ImageBlock,
+    }
+
+    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:
+                logger.debug("Failed to deserialize message block type=%s", block_type, exc_info=True)
+                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 ""