agentshim 0.1.0__tar.gz

agentshim-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: uv sync --dev
+      - run: uv run pytest
+      - run: uv run ruff check .

agentshim-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build distributions
+        run: uv build
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/agentshim
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agentshim-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/

agentshim-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: agentshim
+Version: 0.1.0
+Summary: Provider-agnostic coding-agent CLI shims
+Requires-Python: >=3.10
+Requires-Dist: litellm>=1.0.0
+Requires-Dist: loguru>=0.7.2
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# agentshim
+
+`agentshim` is a small Python package that wraps coding-agent CLIs behind a
+stable interface for higher-level runtimes.
+
+It currently includes:
+
+- a `CodingAgent` base class and provider registry
+- CLI adapters for Claude Code, Codex, Gemini, and Opencode
+- MCP server config dataclasses
+- sandbox settings helpers for Claude Code
+- a lightweight litellm client and isolated subagent helper
+- a trajectory protocol with a no-op implementation
+
+## Install
+
+```bash
+pip install agentshim
+```
+
+For development:
+
+```bash
+uv sync --dev
+uv run pytest
+```
+
+## Quick Example
+
+```python
+from agentshim.claude import ClaudeCodeCodingAgent
+
+agent = ClaudeCodeCodingAgent(model="sonnet")
+result = agent.generate("Summarize the repository layout.", cwd=".")
+print(result)
+```
+
+## Publishing
+
+Build locally with:
+
+```bash
+uv build
+```
+
+Publish with:
+
+```bash
+uv publish
+```

agentshim-0.1.0/README.md

@@ -0,0 +1,50 @@
+# agentshim
+
+`agentshim` is a small Python package that wraps coding-agent CLIs behind a
+stable interface for higher-level runtimes.
+
+It currently includes:
+
+- a `CodingAgent` base class and provider registry
+- CLI adapters for Claude Code, Codex, Gemini, and Opencode
+- MCP server config dataclasses
+- sandbox settings helpers for Claude Code
+- a lightweight litellm client and isolated subagent helper
+- a trajectory protocol with a no-op implementation
+
+## Install
+
+```bash
+pip install agentshim
+```
+
+For development:
+
+```bash
+uv sync --dev
+uv run pytest
+```
+
+## Quick Example
+
+```python
+from agentshim.claude import ClaudeCodeCodingAgent
+
+agent = ClaudeCodeCodingAgent(model="sonnet")
+result = agent.generate("Summarize the repository layout.", cwd=".")
+print(result)
+```
+
+## Publishing
+
+Build locally with:
+
+```bash
+uv build
+```
+
+Publish with:
+
+```bash
+uv publish
+```

agentshim-0.1.0/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-0.1.0/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-0.1.0/agentshim/claude/__init__.py

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

agentshim-0.1.0/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-0.1.0/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