tsugite-cli 0.3.3__py3-none-any.whl

tsugite/docker_cli.py

@@ -0,0 +1,270 @@
+"""Docker CLI wrapper entry points.
+
+This module provides console script entry points for tsugite-docker and
+tsugite-docker-session. The implementation is kept simple to maintain
+the principle of zero coupling with tsugite core.
+"""
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+from uuid import uuid4
+
+
+def docker_main():
+    """Entry point for tsugite-docker wrapper."""
+    # Parse wrapper-specific flags
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("--network", default="host", help="Docker network mode")
+    parser.add_argument("--keep", action="store_true", help="Keep container running")
+    parser.add_argument("--container", help="Use existing container or create named container")
+    parser.add_argument("--image", default="tsugite/runtime", help="Docker image to use")
+
+    args, tsugite_args = parser.parse_known_args()
+
+    # If using existing container, exec into it
+    if args.container:
+        # Check if container exists
+        check = subprocess.run(
+            ["docker", "ps", "-a", "-q", "-f", f"name=^{args.container}$"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+
+        if check.stdout.strip():
+            # Container exists - exec into it (tsugite command available in PATH)
+            cmd = ["docker", "exec", "-it", "-w", "/workspace", args.container, "tsugite"] + tsugite_args
+        else:
+            # Container doesn't exist - create it with this name
+            cmd = _build_run_command(args, tsugite_args, container_name=args.container)
+    else:
+        # New container
+        container_name = f"tsugite-{uuid4().hex[:8]}" if args.keep else None
+        cmd = _build_run_command(args, tsugite_args, container_name)
+
+    # Execute
+    result = subprocess.run(cmd, check=False)
+    sys.exit(result.returncode)
+
+
+def _build_run_command(args, tsugite_args, container_name=None):
+    """Build docker run command."""
+    import os
+
+    cmd = ["docker", "run", "-it"]
+
+    # Container lifecycle
+    if container_name:
+        cmd.extend(["--name", container_name])
+    else:
+        cmd.append("--rm")  # Auto-remove
+
+    # Network
+    cmd.extend(["--network", args.network])
+
+    # Volume mounts
+    # 1. Workspace (read-only for security)
+    cmd.extend(["-v", f"{Path.cwd()}:/workspace:ro"])
+
+    # 2. Config directory (read-only) - for MCP configs, model aliases, etc
+    config_dir = Path(os.getenv("XDG_CONFIG_HOME", Path.home() / ".config")) / "tsugite"
+    if config_dir.exists():
+        cmd.extend(["-v", f"{config_dir}:/root/.config/tsugite:ro"])
+
+    # 3. Cache directory (read-write) - for attachment cache
+    cache_dir = Path(os.getenv("XDG_CACHE_HOME", Path.home() / ".cache")) / "tsugite"
+    if cache_dir.exists():
+        cmd.extend(["-v", f"{cache_dir}:/root/.cache/tsugite"])
+
+    # 4. Forward API keys and important env vars
+    env_vars = ["OPENAI_API_KEY", "ANTHROPIC_API_KEY", "GOOGLE_API_KEY", "GITHUB_TOKEN"]
+    for var in env_vars:
+        if var in os.environ:
+            cmd.extend(["-e", var])
+
+    # Working directory
+    cmd.extend(["-w", "/workspace"])
+
+    # Image and command (ENTRYPOINT already has "tsugite")
+    cmd.append(args.image)
+    cmd.extend(tsugite_args)
+
+    return cmd
+
+
+def session_main():
+    """Entry point for tsugite-docker-session wrapper."""
+    if len(sys.argv) < 2:
+        _print_session_usage()
+        sys.exit(1)
+
+    command = sys.argv[1]
+
+    if command == "start":
+        _start_session(sys.argv[2:])
+    elif command == "stop":
+        _stop_session(sys.argv[2:])
+    elif command == "list":
+        _list_sessions()
+    elif command == "exec":
+        _exec_session(sys.argv[2:])
+    else:
+        print(f"Unknown command: {command}")
+        _print_session_usage()
+        sys.exit(1)
+
+
+def _start_session(args):
+    """Start a persistent container."""
+    import os
+
+    if not args:
+        print("Error: session name required")
+        print("Usage: tsugite-docker-session start NAME [--network NETWORK] [--image IMAGE]")
+        sys.exit(1)
+
+    name = args[0]
+    network = "host"  # Default to host for consistency
+    image = "tsugite/runtime"
+
+    # Parse optional flags
+    i = 1
+    while i < len(args):
+        if args[i] == "--network" and i + 1 < len(args):
+            network = args[i + 1]
+            i += 2
+        elif args[i] == "--image" and i + 1 < len(args):
+            image = args[i + 1]
+            i += 2
+        else:
+            i += 1
+
+    cmd = [
+        "docker",
+        "run",
+        "-d",
+        "--name",
+        name,
+        "--network",
+        network,
+    ]
+
+    # Volume mounts (same as run command)
+    cmd.extend(["-v", f"{Path.cwd()}:/workspace"])
+
+    # Config directory
+    config_dir = Path(os.getenv("XDG_CONFIG_HOME", str(Path.home() / ".config"))) / "tsugite"
+    if config_dir.exists():
+        cmd.extend(["-v", f"{config_dir}:/root/.config/tsugite:ro"])
+
+    # Cache directory
+    cache_dir = Path(os.getenv("XDG_CACHE_HOME", str(Path.home() / ".cache"))) / "tsugite"
+    if cache_dir.exists():
+        cmd.extend(["-v", f"{cache_dir}:/root/.cache/tsugite"])
+
+    # Forward API keys
+    env_vars = ["OPENAI_API_KEY", "ANTHROPIC_API_KEY", "GOOGLE_API_KEY", "GITHUB_TOKEN"]
+    for var in env_vars:
+        if var in os.environ:
+            cmd.extend(["-e", var])
+
+    cmd.extend(["-w", "/workspace", image, "tail", "-f", "/dev/null"])
+
+    result = subprocess.run(cmd, check=False)
+    if result.returncode == 0:
+        print(f"✓ Session '{name}' started")
+        print(f'  Use: tsugite-docker --container {name} run agent.md "task"')
+    sys.exit(result.returncode)
+
+
+def _stop_session(args):
+    """Stop a container."""
+    if not args:
+        print("Error: session name required")
+        print("Usage: tsugite-docker-session stop NAME [--remove]")
+        sys.exit(1)
+
+    name = args[0]
+    remove = "--remove" in args
+
+    # Stop container
+    result = subprocess.run(["docker", "stop", name], check=False)
+    if result.returncode != 0:
+        sys.exit(result.returncode)
+
+    # Remove if requested
+    if remove:
+        result = subprocess.run(["docker", "rm", name], check=False)
+        if result.returncode == 0:
+            print(f"✓ Session '{name}' stopped and removed")
+    else:
+        print(f"✓ Session '{name}' stopped")
+
+    sys.exit(result.returncode)
+
+
+def _list_sessions():
+    """List all tsugite containers."""
+    subprocess.run(
+        [
+            "docker",
+            "ps",
+            "-a",
+            "--filter",
+            "name=tsugite-",
+            "--format",
+            "table {{.Names}}\t{{.Status}}\t{{.CreatedAt}}",
+        ],
+        check=False,
+    )
+
+
+def _exec_session(args):
+    """Execute command in container."""
+    if len(args) < 2:
+        print("Error: session name and command required")
+        print("Usage: tsugite-docker-session exec NAME COMMAND [ARGS...]")
+        sys.exit(1)
+
+    name = args[0]
+    command = args[1:]
+
+    # Check if running, start if needed
+    check = subprocess.run(["docker", "ps", "-q", "-f", f"name=^{name}$"], capture_output=True, text=True, check=False)
+
+    if not check.stdout.strip():
+        print(f"Starting stopped session '{name}'...")
+        subprocess.run(["docker", "start", name], check=False)
+
+    # Execute
+    result = subprocess.run(["docker", "exec", "-it", name] + command, check=False)
+    sys.exit(result.returncode)
+
+
+def _print_session_usage():
+    """Print session management usage."""
+    print(
+        """Usage: tsugite-docker-session COMMAND [ARGS...]
+
+Commands:
+    start NAME [--network NETWORK] [--image IMAGE]
+        Start a new persistent session
+
+    stop NAME [--remove]
+        Stop a session (optionally remove it)
+
+    list
+        List all tsugite sessions
+
+    exec NAME COMMAND [ARGS...]
+        Execute command in session
+
+Examples:
+    tsugite-docker-session start my-work
+    tsugite-docker --container my-work run agent.md "task"
+    tsugite-docker-session exec my-work bash
+    tsugite-docker-session stop my-work
+"""
+    )

tsugite/events/__init__.py

@@ -0,0 +1,55 @@
+"""Event system for UI and API communication."""
+
+from .base import BaseEvent, EventType
+from .bus import EventBus
+from .events import (
+    CodeExecutionEvent,
+    CostSummaryEvent,
+    DebugMessageEvent,
+    ErrorEvent,
+    ExecutionLogsEvent,
+    ExecutionResultEvent,
+    FinalAnswerEvent,
+    InfoEvent,
+    LLMMessageEvent,
+    ObservationEvent,
+    ReasoningContentEvent,
+    ReasoningTokensEvent,
+    StepProgressEvent,
+    StepStartEvent,
+    StreamChunkEvent,
+    StreamCompleteEvent,
+    TaskStartEvent,
+    ToolCallEvent,
+    WarningEvent,
+)
+
+__all__ = [
+    # Base
+    "BaseEvent",
+    "EventType",
+    "EventBus",
+    # Execution
+    "TaskStartEvent",
+    "StepStartEvent",
+    "CodeExecutionEvent",
+    "ToolCallEvent",
+    "ObservationEvent",
+    "FinalAnswerEvent",
+    # LLM
+    "LLMMessageEvent",
+    "ExecutionResultEvent",
+    "ExecutionLogsEvent",
+    "ReasoningContentEvent",
+    "ReasoningTokensEvent",
+    # Meta
+    "InfoEvent",
+    "ErrorEvent",
+    "CostSummaryEvent",
+    "StreamChunkEvent",
+    "StreamCompleteEvent",
+    # Progress
+    "DebugMessageEvent",
+    "WarningEvent",
+    "StepProgressEvent",
+]

tsugite/events/base.py

@@ -0,0 +1,46 @@
+"""Base event model and event type enum."""
+
+from datetime import datetime, timezone
+from enum import IntEnum
+
+from pydantic import BaseModel, Field
+
+
+class EventType(IntEnum):
+    """Event type enumeration."""
+
+    # Core execution events
+    TASK_START = 1
+    STEP_START = 2
+    CODE_EXECUTION = 3
+    TOOL_CALL = 4
+    OBSERVATION = 5
+    ERROR = 8
+    FINAL_ANSWER = 9
+
+    # LLM events
+    LLM_MESSAGE = 10
+    EXECUTION_RESULT = 11
+    EXECUTION_LOGS = 12
+    REASONING_CONTENT = 13
+    REASONING_TOKENS = 14
+
+    # Meta events
+    COST_SUMMARY = 15
+    STREAM_CHUNK = 16
+    STREAM_COMPLETE = 17
+    INFO = 20
+
+    # New progress events
+    DEBUG_MESSAGE = 21
+    WARNING = 22
+    STEP_PROGRESS = 23
+
+
+class BaseEvent(BaseModel):
+    """Base class for all UI events."""
+
+    model_config = {"frozen": True, "use_enum_values": False}
+
+    event_type: EventType = Field(frozen=True)
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))

tsugite/events/bus.py

@@ -0,0 +1,62 @@
+"""EventBus for broadcasting events to multiple handlers."""
+
+import sys
+from typing import Callable, List
+
+from .base import BaseEvent
+
+
+class EventBus:
+    """Broadcast events to multiple handlers with error isolation."""
+
+    def __init__(self):
+        self._handlers: List[Callable[[BaseEvent], None]] = []
+
+    def subscribe(self, handler: Callable[[BaseEvent], None]) -> None:
+        """Subscribe a handler to receive events.
+
+        Args:
+            handler: Callable that accepts a BaseEvent
+        """
+        if handler not in self._handlers:
+            self._handlers.append(handler)
+
+    def unsubscribe(self, handler: Callable[[BaseEvent], None]) -> None:
+        """Unsubscribe a handler.
+
+        Args:
+            handler: Handler to remove
+        """
+        if handler in self._handlers:
+            self._handlers.remove(handler)
+
+    def emit(self, event: BaseEvent) -> None:
+        """Emit event to all subscribers with error isolation.
+
+        Args:
+            event: Event to broadcast
+        """
+        for handler in self._handlers:
+            try:
+                handler(event)
+            except Exception as e:
+                import traceback
+
+                print(f"Handler error: {e}", file=sys.stderr)
+                traceback.print_exc(file=sys.stderr)
+
+    def has_handlers(self) -> bool:
+        """Check if any handlers are subscribed.
+
+        Returns:
+            True if handlers exist
+        """
+        return len(self._handlers) > 0
+
+    def handler_count(self) -> int:
+        """Get number of subscribed handlers.
+
+        Returns:
+            Handler count
+        """
+        return len(self._handlers)

tsugite/events/events.py

@@ -0,0 +1,224 @@
+"""All event classes consolidated in one module.
+
+Error Handling Patterns:
+------------------------
+1. Tool Results (ObservationEvent):
+   - Success: ObservationEvent(success=True, observation="result", tool="tool_name")
+   - Failure: ObservationEvent(success=False, error="error msg", tool="tool_name")
+
+2. Code Execution (ExecutionResultEvent):
+   - Success: ExecutionResultEvent(success=True, logs=[...], output="result")
+   - Failure: ExecutionResultEvent(success=False, error="error msg")
+
+3. General/Fatal Errors (ErrorEvent):
+   - ErrorEvent(error="error msg", error_type="Error Type", step=N)
+   - Used for: Format errors, max turns exceeded, critical failures
+"""
+
+from typing import Any, Dict, Optional
+
+from pydantic import Field
+
+from .base import BaseEvent, EventType
+
+# ============================================================================
+# Execution Events
+# ============================================================================
+
+
+class TaskStartEvent(BaseEvent):
+    """Agent execution starts."""
+
+    event_type: EventType = Field(default=EventType.TASK_START, frozen=True)
+    task: str
+    model: str
+
+
+class StepStartEvent(BaseEvent):
+    """New reasoning turn."""
+
+    event_type: EventType = Field(default=EventType.STEP_START, frozen=True)
+    step: int = Field(ge=1)
+    max_turns: Optional[int] = Field(default=None, ge=1)
+
+
+class CodeExecutionEvent(BaseEvent):
+    """Code being executed."""
+
+    event_type: EventType = Field(default=EventType.CODE_EXECUTION, frozen=True)
+    code: str
+    language: str = "python"
+
+
+class ToolCallEvent(BaseEvent):
+    """Tool invocation."""
+
+    event_type: EventType = Field(default=EventType.TOOL_CALL, frozen=True)
+    tool: str
+    args: Dict[str, Any] = Field(default_factory=dict)
+
+
+class ObservationEvent(BaseEvent):
+    """Observation from tool execution or code execution.
+
+    Usage:
+    - Tool success: ObservationEvent(success=True, observation="result", tool="tool_name")
+    - Tool failure: ObservationEvent(success=False, error="error", tool="tool_name")
+    - Code execution: ObservationEvent(observation="output", tool=None)
+
+    Note: For code execution, tool is None and ExecutionResultEvent may be emitted
+    separately with structured logs/output.
+    """
+
+    event_type: EventType = Field(default=EventType.OBSERVATION, frozen=True)
+    observation: str = ""
+    tool: Optional[str] = None
+    success: bool = True
+    error: Optional[str] = None
+
+
+class FinalAnswerEvent(BaseEvent):
+    """Agent completed."""
+
+    event_type: EventType = Field(default=EventType.FINAL_ANSWER, frozen=True)
+    answer: str
+    turns: Optional[int] = Field(default=None, ge=1)
+    tokens: Optional[int] = Field(default=None, ge=0)
+    cost: Optional[float] = Field(default=None, ge=0)
+
+
+# ============================================================================
+# LLM Events
+# ============================================================================
+
+
+class LLMMessageEvent(BaseEvent):
+    """Reasoning/thought process."""
+
+    event_type: EventType = Field(default=EventType.LLM_MESSAGE, frozen=True)
+    content: str
+    title: Optional[str] = None
+    step: Optional[int] = Field(default=None, ge=1)
+
+
+class ExecutionResultEvent(BaseEvent):
+    """Code execution result with structured logs and output."""
+
+    event_type: EventType = Field(default=EventType.EXECUTION_RESULT, frozen=True)
+    logs: list[str] = Field(default_factory=list)
+    output: Optional[str] = None
+    success: bool = True
+    error: Optional[str] = None
+
+
+class ExecutionLogsEvent(BaseEvent):
+    """Execution logs."""
+
+    event_type: EventType = Field(default=EventType.EXECUTION_LOGS, frozen=True)
+    logs: str
+
+
+class ReasoningContentEvent(BaseEvent):
+    """Model reasoning (Claude, Deepseek)."""
+
+    event_type: EventType = Field(default=EventType.REASONING_CONTENT, frozen=True)
+    content: str
+    step: Optional[int] = Field(default=None, ge=1)
+
+
+class ReasoningTokensEvent(BaseEvent):
+    """Reasoning token count (o1, o3)."""
+
+    event_type: EventType = Field(default=EventType.REASONING_TOKENS, frozen=True)
+    tokens: int = Field(ge=0)
+    step: Optional[int] = Field(default=None, ge=1)
+
+
+# ============================================================================
+# Meta Events
+# ============================================================================
+
+
+class InfoEvent(BaseEvent):
+    """Informational message."""
+
+    event_type: EventType = Field(default=EventType.INFO, frozen=True)
+    message: str
+
+
+class ErrorEvent(BaseEvent):
+    """Execution error."""
+
+    event_type: EventType = Field(default=EventType.ERROR, frozen=True)
+    error: str
+    error_type: Optional[str] = None
+    step: Optional[int] = Field(default=None, ge=1)
+    traceback: Optional[str] = None
+
+
+class CostSummaryEvent(BaseEvent):
+    """Token/cost metrics with prompt caching support.
+
+    Prompt caching fields (supported by OpenAI, Anthropic, AWS Bedrock, Deepseek):
+    - cached_tokens: Total cached tokens read (unified across providers)
+    - cache_creation_input_tokens: Tokens used to create cache (Anthropic-specific)
+    - cache_read_input_tokens: Tokens read from cache (Anthropic-specific)
+
+    For Anthropic, both creation and read tokens are also included in cached_tokens.
+    """
+
+    event_type: EventType = Field(default=EventType.COST_SUMMARY, frozen=True)
+    tokens: Optional[int] = Field(default=None, ge=0)
+    cost: Optional[float] = Field(default=None, ge=0)
+    model: Optional[str] = None
+    duration_seconds: Optional[float] = Field(default=None, ge=0)
+
+    # Prompt caching fields
+    cached_tokens: Optional[int] = Field(default=None, ge=0)
+    cache_creation_input_tokens: Optional[int] = Field(default=None, ge=0)
+    cache_read_input_tokens: Optional[int] = Field(default=None, ge=0)
+
+
+class StreamChunkEvent(BaseEvent):
+    """Streaming response chunk."""
+
+    event_type: EventType = Field(default=EventType.STREAM_CHUNK, frozen=True)
+    chunk: str
+
+
+class StreamCompleteEvent(BaseEvent):
+    """Streaming finished."""
+
+    event_type: EventType = Field(default=EventType.STREAM_COMPLETE, frozen=True)
+    complete: bool = True
+
+
+# ============================================================================
+# Progress Events
+# ============================================================================
+
+
+class DebugMessageEvent(BaseEvent):
+    """Debug output."""
+
+    event_type: EventType = Field(default=EventType.DEBUG_MESSAGE, frozen=True)
+    message: str
+    context: Optional[Dict[str, Any]] = None
+
+
+class WarningEvent(BaseEvent):
+    """Warning message."""
+
+    event_type: EventType = Field(default=EventType.WARNING, frozen=True)
+    message: str
+    category: Optional[str] = None
+
+
+class StepProgressEvent(BaseEvent):
+    """Progress update."""
+
+    event_type: EventType = Field(default=EventType.STEP_PROGRESS, frozen=True)
+    message: str
+    step: Optional[int] = Field(default=None, ge=1)
+    total: Optional[int] = Field(default=None, ge=1)
+    percentage: Optional[float] = Field(default=None, ge=0, le=100)

tsugite/exceptions.py

@@ -0,0 +1,40 @@
+"""Custom exception classes for Tsugite."""
+
+from typing import Any, List, Optional
+
+
+class AgentExecutionError(RuntimeError):
+    """Exception raised when agent execution fails.
+
+    Includes execution details for debugging and analysis.
+
+    Attributes:
+        message: Error message
+        execution_steps: List of step results from agent execution
+        token_usage: Token usage count (if available)
+        cost: Cost of execution (if available)
+        step_count: Number of steps taken
+    """
+
+    def __init__(
+        self,
+        message: str,
+        execution_steps: Optional[List[Any]] = None,
+        token_usage: Optional[int] = None,
+        cost: Optional[float] = None,
+        step_count: int = 0,
+    ):
+        """Initialize AgentExecutionError.
+
+        Args:
+            message: Error message
+            execution_steps: List of step results from execution
+            token_usage: Token usage count
+            cost: Cost of execution
+            step_count: Number of steps taken
+        """
+        super().__init__(message)
+        self.execution_steps = execution_steps or []
+        self.token_usage = token_usage
+        self.cost = cost
+        self.step_count = step_count