agentshim 0.1.0__py3-none-any.whl

agentshim/__init__.py

@@ -0,0 +1,24 @@
+from .base import CodingAgent
+from .claude import ClaudeCodeCodingAgent
+from .codex import CodexCodingAgent
+from .gemini import GeminiCodingAgent
+from .llm_client import LiteLLMClient
+from .mcp_config import HttpMcpServer, McpServerConfig, StdioMcpServer
+from .opencode import OpencodeCodingAgent
+from .sandbox import SandboxConfig
+from .subagent import call_subagent, litellm_call_with_retry
+
+__all__ = [
+    "CodingAgent",
+    "CodexCodingAgent",
+    "GeminiCodingAgent",
+    "OpencodeCodingAgent",
+    "ClaudeCodeCodingAgent",
+    "HttpMcpServer",
+    "McpServerConfig",
+    "StdioMcpServer",
+    "SandboxConfig",
+    "call_subagent",
+    "litellm_call_with_retry",
+    "LiteLLMClient",
+]

agentshim/base.py

@@ -0,0 +1,52 @@
+from abc import ABC, abstractmethod
+from typing import Any, TypeVar
+
+from agentshim.trajectory import NullTrajectoryRecorder, TrajectoryRecorderProtocol
+
+_T = TypeVar("_T")
+
+AGENT_REGISTRY: dict[str, Any] = {}
+
+
+def register_provider(*names: str) -> Any:
+    """Decorator to register a coding agent provider.
+
+    Args:
+        *names: List of provider names/aliases (case-insensitive).
+    """
+
+    def decorator(cls: _T) -> _T:
+        for name in names:
+            AGENT_REGISTRY[name.lower()] = cls
+        return cls
+
+    return decorator
+
+
+class CodingAgent(ABC):
+    """Abstract base class for coding agents."""
+
+    recorder: TrajectoryRecorderProtocol = NullTrajectoryRecorder()
+    event_handler: Any | None = None
+
+    @abstractmethod
+    def generate(
+        self,
+        prompt: str,
+        cwd: str | None = None,
+        timeout: int = 300,
+        silent: bool = False,
+    ) -> str:
+        """One-shot prompt → reply. Equivalent to a fresh ``start_session``
+        followed by a single ``session.generate(prompt)``; no conversation
+        state is retained. Use ``start_session`` for multi-turn flows.
+
+        Args:
+            prompt: The prompt to send to the agent.
+            cwd: Optional working directory context.
+            timeout: Timeout in seconds.
+            silent: If True, suppress stdout printing of the agent's output.
+
+        Returns:
+            Generated text.
+        """

agentshim/claude/__init__.py

@@ -0,0 +1,3 @@
+from .agent import ClaudeCodeCodingAgent, ClaudeGenerationSession
+
+__all__ = ["ClaudeCodeCodingAgent", "ClaudeGenerationSession"]

agentshim/claude/agent.py

@@ -0,0 +1,264 @@
+import json
+import subprocess
+import time
+from collections.abc import Callable
+from typing import Any
+
+from agentshim.trajectory import TrajectoryRecorderProtocol
+
+from ..base import register_provider
+from ..cli_agent import CLICodingAgent, CLIGenerationSession
+from ..events import AgentEventHandler
+from ..mcp_config import HttpMcpServer, McpServerConfig
+from ..sandbox import SandboxConfig, build_claude_sandbox_settings, resolve_sandbox
+from ..usage import ProviderUsage, TokenUsage
+from .events import (
+    ClaudeEvent,
+    MultiEvent,
+    ResultEvent,
+    SystemEvent,
+    TextEvent,
+    ToolResultEvent,
+    ToolUseEvent,
+)
+
+
+class ClaudeGenerationSession(CLIGenerationSession):
+    def __init__(self, **kwargs: Any):
+        super().__init__(**kwargs)
+        # Initialize state required for stream processing
+        self.tool_map: dict[str, str] = {}
+        self.tool_start_times: dict[str, float] = {}
+        self.tool_args: dict[str, Any] = {}
+        self.final_result: str | None = None
+
+    def _process_stdout(self, line: str) -> None:
+        """Process a line from stdout."""
+        if not line:
+            return
+        try:
+            data = json.loads(line)
+            event = ClaudeEvent.from_dict(data)
+            if event:
+                self._handle_event(event)
+        except json.JSONDecodeError:
+            # Fallback for non-JSON lines - still accumulate them
+            self.stdout_lines.append(line.rstrip())
+            if not self.silent:
+                if self._at_line_start:
+                    self._log_raw(f"{self.log_prefix} ")
+                self._log_raw(line.rstrip() + "\n")
+                self._at_line_start = True
+
+    def _handle_event(self, event: ClaudeEvent):
+        """Handle a single parsed Claude event."""
+        if isinstance(event, MultiEvent):
+            for sub_event in event.events:
+                self._handle_event(sub_event)
+            return
+
+        self._update_state(event)
+
+        if not self.silent:
+            self._render_event(event)
+
+    def _update_state(self, event: ClaudeEvent):
+        """Update internal state based on the event."""
+        if isinstance(event, SystemEvent):
+            if self.session_id is None and event.session_id:
+                self.session_id = event.session_id
+            return
+
+        if isinstance(event, TextEvent):
+            self.stdout_lines.append(event.text)
+            if self.event_handler:
+                self.event_handler.on_thinking(event.text)
+
+        elif isinstance(event, ToolUseEvent):
+            if event.tool_id:
+                self.tool_map[event.tool_id] = event.tool_name
+                self.tool_start_times[event.tool_id] = time.time()
+                self.tool_args[event.tool_id] = event.parameters
+                if self.event_handler:
+                    self.event_handler.on_tool_call(event.tool_name, event.parameters)
+
+        elif isinstance(event, ToolResultEvent):
+            if event.tool_id:
+                event.tool_name_resolved = self.tool_map.get(event.tool_id, "Tool")
+
+                start_time = self.tool_start_times.get(event.tool_id)
+                duration = time.time() - start_time if start_time else None
+                args = self.tool_args.get(event.tool_id, {})
+
+                self.recorder.add_tool_call(
+                    tool=event.tool_name_resolved,
+                    args=args,
+                    stdout=event.output,
+                    duration=duration,
+                )
+                if self.event_handler:
+                    self.event_handler.on_tool_result(
+                        tool=event.tool_name_resolved,
+                        stdout=event.output,
+                        duration=duration,
+                    )
+
+        elif isinstance(event, ResultEvent):
+            self.final_result = event.result
+            # Anthropic reports cache_creation + cache_read as disjoint
+            # from input_tokens; fold them into input_tokens to match the
+            # crucible invariant (cached ⊆ input).
+            usage = event.usage or {}
+            cached = int(usage.get("cache_creation_input_tokens") or 0) + int(usage.get("cache_read_input_tokens") or 0)
+            self.usage = ProviderUsage(
+                tokens=TokenUsage(
+                    input_tokens=int(usage.get("input_tokens") or 0) + cached,
+                    output_tokens=int(usage.get("output_tokens") or 0),
+                    cached_input_tokens=cached,
+                    turns=int(event.num_turns or 0),
+                ),
+                total_cost_usd=event.total_cost_usd,
+                provider="claude",
+            )
+
+    def _render_event(self, event: ClaudeEvent):
+        """Render the event to stdout."""
+        if isinstance(event, TextEvent):
+            self._print_stream_content(event.text)
+            return
+
+        if not self._at_line_start:
+            self._log_raw("\n")
+            self._at_line_start = True
+
+        output = event.render(self.log_prefix)
+        if output:
+            self._log_raw(output + "\n")
+
+    def run(self, prompt: str) -> str:
+        """Execute the command and return the result."""
+        super().run(prompt)
+        if self.final_result:
+            return self.final_result
+        return "\n".join(self.stdout_lines)
+
+
+@register_provider("claude", "claude-code", "anthropic")
+class ClaudeCodeCodingAgent(CLICodingAgent):
+    """Coding agent implementation using the Claude Code CLI tool."""
+
+    def __init__(
+        self,
+        model: str | None = None,
+        recorder: TrajectoryRecorderProtocol | None = None,
+        event_handler: AgentEventHandler | None = None,
+        mcp_servers: list[McpServerConfig] | None = None,
+        sandbox: bool | SandboxConfig = False,
+    ):
+        """Initialize the Claude Code coding agent.
+
+        Args:
+            model: Optional model name to use with Claude Code. If None, uses default.
+            recorder: Trajectory recorder instance.
+            event_handler: Optional event handler for UI updates.
+            mcp_servers: Optional list of MCP server configurations.
+            sandbox: If True (or a ``SandboxConfig``), enable Claude Code's
+                native sandbox (bubblewrap on Linux / Seatbelt on macOS)
+                by injecting a ``sandbox`` settings block via
+                ``--settings``. Only bash subprocess commands are
+                sandboxed; the Claude process itself is not wrapped.
+                Defaults to False (no sandbox).
+        """
+        super().__init__("claude", model, recorder, event_handler, mcp_servers)
+        self.sandbox = resolve_sandbox(sandbox)
+        if self.sandbox is not None:
+            # Without this, Claude Code cd's into a per-invocation scratch dir
+            # under <project-root>/.local_tmp/claude-$UID/cwd-* before every
+            # Bash call. That dir is outside the sandbox's allow_write set, so
+            # every sandboxed Bash invocation fails with EROFS before its
+            # command runs. Maintaining the project cwd avoids the scratch dir.
+            self.env["CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR"] = "1"
+
+    @property
+    def claude_path(self) -> str:
+        """Return path to claude binary (for backward compatibility)."""
+        return self.binary_path
+
+    @property
+    def _log_prefix(self) -> str:
+        """Return the log prefix for this agent."""
+        return "[Claude]"
+
+    def _build_mcp_config_json(self) -> str:
+        """Build the JSON string for --mcp-config.
+
+        Claude Code runs the rendered config through ``--strict-mcp-config``
+        validation, which requires HTTP servers to declare ``type``
+        explicitly (``"sse"`` or ``"http"``). ``HttpMcpServer`` represents
+        the SSE transport (the field doc says HTTP/SSE; current call sites
+        use ``…/sse`` URLs), so emit ``type: "sse"``. ``headers`` is
+        included only when non-empty, mirroring the schema's optional
+        nature.
+        """
+        servers: dict[str, dict[str, Any]] = {}
+        for server in self.mcp_servers:
+            if isinstance(server, HttpMcpServer):
+                http_entry: dict[str, Any] = {"type": "sse", "url": server.url}
+                if server.headers:
+                    http_entry["headers"] = dict(server.headers)
+                servers[server.name] = http_entry
+            else:
+                entry: dict[str, Any] = {"command": server.command, "args": server.args}
+                if server.env:
+                    entry["env"] = server.env
+                servers[server.name] = entry
+        return json.dumps({"mcpServers": servers})
+
+    def _get_command(self, prompt: str, resume_session_id: str | None = None) -> list[str]:
+        cmd = [
+            self.binary_path,
+            "-p",  # Print mode, accepts prompt from stdin
+            "--dangerously-skip-permissions",  # Auto-approval mode
+            "--output-format",
+            "stream-json",
+            "--verbose",
+        ]
+        if resume_session_id:
+            cmd.extend(["--resume", resume_session_id])
+        cmd.append(prompt)
+        if self.model:
+            cmd.extend(["--model", self.model])
+        if self.mcp_servers:
+            cmd.extend(
+                [
+                    "--mcp-config",
+                    self._build_mcp_config_json(),
+                    "--strict-mcp-config",
+                ]
+            )
+        if self.sandbox is not None:
+            cmd.extend(["--settings", json.dumps(build_claude_sandbox_settings(self.sandbox))])
+        return cmd
+
+    def _create_session(
+        self,
+        cmd: list[str],
+        cwd: str | None = None,
+        timeout: int = 300,
+        silent: bool = False,
+        recorder: TrajectoryRecorderProtocol | None = None,
+        on_process_started: Callable[[subprocess.Popen[str]], None] | None = None,
+    ) -> ClaudeGenerationSession:
+        return ClaudeGenerationSession(
+            binary_name=self.binary_name,
+            env=self.env,
+            log_prefix=self._log_prefix,
+            cmd=cmd,
+            logger=self.logger,
+            cwd=cwd,
+            timeout=timeout,
+            silent=silent,
+            recorder=recorder,
+            event_handler=self.event_handler,
+            on_process_started=on_process_started,
+        )

agentshim/claude/events.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, cast
+
+from ..utils import truncate_content, truncate_tool_params
+
+
+class ClaudeEvent(ABC):
+    """Base class for Claude Code stream events."""
+
+    @abstractmethod
+    def render(self, log_prefix: str) -> str | None:
+        """Render the event as a string for terminal output."""
+
+    @staticmethod
+    def from_dict(data: dict[str, Any]) -> ClaudeEvent | None:
+        """Factory method to create events from JSON data."""
+        event_type = data.get("type")
+
+        if event_type == "system":
+            return SystemEvent(data)
+        if event_type == "assistant":
+            message = data.get("message", {})
+            content_blocks = message.get("content", [])
+            events: list[ClaudeEvent] = []
+            for block in content_blocks:
+                block_type = block.get("type")
+                if block_type == "text":
+                    events.append(TextEvent(block.get("text", "")))
+                elif block_type == "tool_use":
+                    events.append(
+                        ToolUseEvent(
+                            tool_name=block.get("name", "Tool"),
+                            tool_id=block.get("id"),
+                            parameters=block.get("input"),
+                        )
+                    )
+            return MultiEvent(events) if events else None
+        if event_type == "user":
+            message = data.get("message", {})
+            content_blocks = message.get("content", [])
+            for block in content_blocks:
+                if block.get("type") == "tool_result":
+                    return ToolResultEvent(
+                        output=block.get("content", ""),
+                        tool_id=block.get("tool_use_id"),
+                    )
+            return None
+        if event_type == "result":
+            return ResultEvent(
+                result=data.get("result", ""),
+                num_turns=data.get("num_turns"),
+                usage=data.get("usage"),
+                total_cost_usd=data.get("total_cost_usd"),
+            )
+
+        return None
+
+
+class MultiEvent(ClaudeEvent):
+    """Container for multiple events from a single message."""
+
+    def __init__(self, events: list[ClaudeEvent]):
+        self.events = events
+
+    def render(self, log_prefix: str) -> str | None:
+        # MultiEvent doesn't render itself; events are handled individually
+        return None
+
+
+class SystemEvent(ClaudeEvent):
+    """System initialization event.
+
+    Carries the provider ``session_id`` on the ``init`` subtype, used to
+    enable conversation resumption via ``claude --resume <id>``.
+    """
+
+    def __init__(self, data: dict[str, Any]):
+        self.data = data
+        self.session_id: str | None = data.get("session_id")
+
+    def render(self, log_prefix: str) -> str | None:
+        # System events are silent
+        return None
+
+
+class TextEvent(ClaudeEvent):
+    """Assistant text content event."""
+
+    def __init__(self, text: str):
+        self.text = text
+
+    def render(self, log_prefix: str) -> str | None:
+        # Text rendering is handled specially due to streaming
+        return self.text
+
+
+class ToolUseEvent(ClaudeEvent):
+    """Tool call event from assistant."""
+
+    def __init__(self, tool_name: str, tool_id: str | None, parameters: Any):
+        self.tool_name = tool_name
+        self.tool_id = tool_id
+        self.parameters = parameters
+
+    def render(self, log_prefix: str) -> str:
+        truncated = truncate_tool_params(self.tool_name, self.parameters)
+        return f"{log_prefix} \033[34m[Tool Use] {self.tool_name} {truncated}\033[0m"
+
+
+class ToolResultEvent(ClaudeEvent):
+    """Tool execution result event."""
+
+    def __init__(self, output: Any, tool_id: str | None):
+        # Convert output to string if it's not already
+        if isinstance(output, list):
+            # Handle list content (e.g., from tool_result blocks with multiple items)
+            self.output = "\n".join(str(item) for item in cast("list[Any]", output))
+        else:
+            self.output = str(output) if output else ""
+        self.tool_id = tool_id
+        self.tool_name_resolved: str = "Tool"  # To be set externally
+
+    def render(self, log_prefix: str) -> str:
+        if not self.output:
+            return f"{log_prefix} \033[32m{self.tool_name_resolved} ran successfully\033[0m"
+        truncated = truncate_content(self.output)
+        return f"{log_prefix} \033[32m[Tool Result] {truncated}\033[0m"
+
+
+class ResultEvent(ClaudeEvent):
+    """Final session summary event."""
+
+    def __init__(
+        self,
+        result: str,
+        num_turns: int | None = None,
+        usage: dict[str, Any] | None = None,
+        total_cost_usd: float | None = None,
+    ):
+        self.result = result
+        self.num_turns = num_turns
+        self.usage = usage
+        self.total_cost_usd = total_cost_usd
+
+    def render(self, log_prefix: str) -> str | None:
+        # Result events are silent (result is captured separately)
+        return None

agentshim/claude/hooks/confine_reads.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""Claude Code ``PreToolUse`` hook that denies file reads/edits outside an allowlist.
+
+Wired up via ``SandboxConfig.confine_native_reads_to`` — see
+``agentshim/sandbox.py``. The hook is invoked by Claude Code for each
+tool call matching ``Read|Glob|Grep|Edit|Write``. It parses the JSON input
+on stdin, resolves the tool's target path, and rejects the call if the path
+doesn't land under one of the allowed roots passed on argv.
+
+Usage::
+
+    confine_reads.py <allowed_root> [<allowed_root> ...]
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any
+
+
+def _candidate_path(tool_input: dict[str, Any]) -> str | None:
+    """Best-effort extraction of the filesystem target from a tool_input blob."""
+    for key in ("file_path", "path", "notebook_path"):
+        value = tool_input.get(key)
+        if isinstance(value, str) and value:
+            return value
+    return None
+
+
+def _is_under(path: str, roots: list[str]) -> bool:
+    for root in roots:
+        if path == root:
+            return True
+        if path.startswith(root.rstrip(os.sep) + os.sep):
+            return True
+    return False
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        # Misconfigured hook — don't block the tool, just let it through.
+        return 0
+
+    roots = [os.path.realpath(p) for p in sys.argv[1:]]
+
+    try:
+        payload: dict[str, Any] = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        return 0
+
+    tool_input: dict[str, Any] = payload.get("tool_input") or {}
+    candidate = _candidate_path(tool_input)
+    if not candidate:
+        # Tool call has no path argument (e.g. Glob without `path` defaults to cwd).
+        return 0
+
+    target = os.path.realpath(os.path.abspath(candidate))
+    if _is_under(target, roots):
+        return 0
+
+    decision = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": (
+                f"Path {target!r} is outside the sandbox roots {roots}. Stay inside the working directory."
+            ),
+        }
+    }
+    json.dump(decision, sys.stdout)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agentshim/claude_events.py

@@ -0,0 +1,21 @@
+"""Compatibility shim for older ``agentshim.claude_events`` imports."""
+
+from .claude.events import (
+    ClaudeEvent,
+    MultiEvent,
+    ResultEvent,
+    SystemEvent,
+    TextEvent,
+    ToolResultEvent,
+    ToolUseEvent,
+)
+
+__all__ = [
+    "ClaudeEvent",
+    "MultiEvent",
+    "ResultEvent",
+    "SystemEvent",
+    "TextEvent",
+    "ToolResultEvent",
+    "ToolUseEvent",
+]