agentshim 0.3.0__tar.gz → 0.4.0__tar.gz

{agentshim-0.3.0 → agentshim-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentshim
-Version: 0.3.0
+Version: 0.4.0
 Summary: Provider-agnostic coding-agent CLI shims
 Requires-Python: >=3.10
 Requires-Dist: litellm>=1.0.0
@@ -25,7 +25,6 @@ prompting, session resumption, event parsing, or MCP configuration.
 - MCP server config models for providers that support MCP
 - sandbox settings helpers for Claude Code
 - a lightweight LiteLLM client and subagent helper
-- trajectory/usage helpers used by higher-level runtimes
 
 ## Install
 
@@ -81,7 +80,79 @@ reply = agent.generate("Write a short summary of this codebase.", cwd=".")
 print(reply)
 ```
 
-### 2. Instantiate a Specific Provider Directly
+### 2. Handle Agent Events
+
+By default, `agentshim` prints provider events to the terminal through a
+`ConsoleEventHandler`. That default is used only when you do not provide your
+own event handler and `silent=False`.
+
+If you pass `event_handler=...`, you take ownership of event handling. The
+built-in console printer is not added implicitly, which avoids surprising
+duplicate output.
+
+```python
+from agentshim import CodingAgent
+
+
+class MyHandler:
+    def on_thinking(self, text: str) -> None:
+        ...
+
+    def on_tool_call(self, tool: str, args=None) -> None:
+        ...
+
+    def on_tool_result(
+        self,
+        tool: str,
+        stdout: str = "",
+        stderr: str = "",
+        exit_code: int | None = None,
+        duration: float | None = None,
+    ) -> None:
+        ...
+
+    def on_usage(self, usage: dict) -> None:
+        ...
+
+
+agent = CodingAgent(provider="claude", event_handler=MyHandler())
+agent.generate("Inspect this repository.")
+```
+
+To keep the default console output and add your own handler, compose them
+explicitly:
+
+```python
+from agentshim import CodingAgent, ConsoleEventHandler
+
+agent = CodingAgent(
+    provider="claude",
+    event_handlers=[
+        ConsoleEventHandler(),
+        MyHandler(),
+    ],
+)
+agent.generate("Inspect this repository.")
+```
+
+You can also build the composition yourself:
+
+```python
+from agentshim import CompositeEventHandler, ConsoleEventHandler
+
+handler = CompositeEventHandler([ConsoleEventHandler(), MyHandler()])
+agent = CodingAgent(provider="codex", event_handler=handler)
+```
+
+Use `silent=True` to suppress the default console handler when you have not
+provided any handler:
+
+```python
+agent = CodingAgent(provider="claude")
+reply = agent.generate("Return only the answer.", silent=True)
+```
+
+### 3. Instantiate a Specific Provider Directly
 
 If you already know which backend you want, construct the provider class
 yourself.
@@ -103,7 +174,7 @@ The bundled provider classes are:
 - `GeminiCodingAgent`
 - `OpencodeCodingAgent`
 
-### 3. Configure MCP Servers
+### 4. Configure MCP Servers
 
 Claude Code and Codex can be configured with MCP servers by passing
 `HttpMcpServer` and `StdioMcpServer` objects at construction time.
@@ -154,14 +225,13 @@ class MyAgent(BaseCodingAgent):
         self,
         model: str | None = None,
         region: str | None = None,
-        recorder=None,
         event_handler=None,
+        event_handlers=None,
         mcp_servers=None,
         sandbox=False,
     ):
         self.model = model
         self.region = region
-        self.recorder = recorder
         self.event_handler = event_handler
 
     def generate(self, prompt: str, cwd=None, timeout=300, silent=False) -> str:
@@ -181,7 +251,7 @@ Notes:
 - Registration is import-driven. Your provider is available only after the module defining it has been imported in the current Python process.
 - `list_providers()` returns canonical provider names only. Aliases resolve via `get_provider_class(...)` and `CodingAgent(provider=...)`.
 - `register_provider(...)` rejects invalid names, abstract classes, and accidental name collisions unless you pass `overwrite=True`.
-- If you want `CodingAgent(...)` to instantiate your provider, its constructor should accept the shared kwargs `model`, `recorder`, `event_handler`, `mcp_servers`, and `sandbox` as needed.
+- If you want `CodingAgent(...)` to instantiate your provider, its constructor should accept the shared kwargs `model`, `event_handler`, `event_handlers`, `mcp_servers`, and `sandbox` as needed.
 - If your provider needs extra constructor arguments beyond the shared portable set, pass them via `backend_kwargs={...}` when constructing `CodingAgent(...)`.
 
 ## Development

{agentshim-0.3.0 → agentshim-0.4.0}/README.md

@@ -14,7 +14,6 @@ prompting, session resumption, event parsing, or MCP configuration.
 - MCP server config models for providers that support MCP
 - sandbox settings helpers for Claude Code
 - a lightweight LiteLLM client and subagent helper
-- trajectory/usage helpers used by higher-level runtimes
 
 ## Install
 
@@ -70,7 +69,79 @@ reply = agent.generate("Write a short summary of this codebase.", cwd=".")
 print(reply)
 ```
 
-### 2. Instantiate a Specific Provider Directly
+### 2. Handle Agent Events
+
+By default, `agentshim` prints provider events to the terminal through a
+`ConsoleEventHandler`. That default is used only when you do not provide your
+own event handler and `silent=False`.
+
+If you pass `event_handler=...`, you take ownership of event handling. The
+built-in console printer is not added implicitly, which avoids surprising
+duplicate output.
+
+```python
+from agentshim import CodingAgent
+
+
+class MyHandler:
+    def on_thinking(self, text: str) -> None:
+        ...
+
+    def on_tool_call(self, tool: str, args=None) -> None:
+        ...
+
+    def on_tool_result(
+        self,
+        tool: str,
+        stdout: str = "",
+        stderr: str = "",
+        exit_code: int | None = None,
+        duration: float | None = None,
+    ) -> None:
+        ...
+
+    def on_usage(self, usage: dict) -> None:
+        ...
+
+
+agent = CodingAgent(provider="claude", event_handler=MyHandler())
+agent.generate("Inspect this repository.")
+```
+
+To keep the default console output and add your own handler, compose them
+explicitly:
+
+```python
+from agentshim import CodingAgent, ConsoleEventHandler
+
+agent = CodingAgent(
+    provider="claude",
+    event_handlers=[
+        ConsoleEventHandler(),
+        MyHandler(),
+    ],
+)
+agent.generate("Inspect this repository.")
+```
+
+You can also build the composition yourself:
+
+```python
+from agentshim import CompositeEventHandler, ConsoleEventHandler
+
+handler = CompositeEventHandler([ConsoleEventHandler(), MyHandler()])
+agent = CodingAgent(provider="codex", event_handler=handler)
+```
+
+Use `silent=True` to suppress the default console handler when you have not
+provided any handler:
+
+```python
+agent = CodingAgent(provider="claude")
+reply = agent.generate("Return only the answer.", silent=True)
+```
+
+### 3. Instantiate a Specific Provider Directly
 
 If you already know which backend you want, construct the provider class
 yourself.
@@ -92,7 +163,7 @@ The bundled provider classes are:
 - `GeminiCodingAgent`
 - `OpencodeCodingAgent`
 
-### 3. Configure MCP Servers
+### 4. Configure MCP Servers
 
 Claude Code and Codex can be configured with MCP servers by passing
 `HttpMcpServer` and `StdioMcpServer` objects at construction time.
@@ -143,14 +214,13 @@ class MyAgent(BaseCodingAgent):
         self,
         model: str | None = None,
         region: str | None = None,
-        recorder=None,
         event_handler=None,
+        event_handlers=None,
         mcp_servers=None,
         sandbox=False,
     ):
         self.model = model
         self.region = region
-        self.recorder = recorder
         self.event_handler = event_handler
 
     def generate(self, prompt: str, cwd=None, timeout=300, silent=False) -> str:
@@ -170,7 +240,7 @@ Notes:
 - Registration is import-driven. Your provider is available only after the module defining it has been imported in the current Python process.
 - `list_providers()` returns canonical provider names only. Aliases resolve via `get_provider_class(...)` and `CodingAgent(provider=...)`.
 - `register_provider(...)` rejects invalid names, abstract classes, and accidental name collisions unless you pass `overwrite=True`.
-- If you want `CodingAgent(...)` to instantiate your provider, its constructor should accept the shared kwargs `model`, `recorder`, `event_handler`, `mcp_servers`, and `sandbox` as needed.
+- If you want `CodingAgent(...)` to instantiate your provider, its constructor should accept the shared kwargs `model`, `event_handler`, `event_handlers`, `mcp_servers`, and `sandbox` as needed.
 - If your provider needs extra constructor arguments beyond the shared portable set, pass them via `backend_kwargs={...}` when constructing `CodingAgent(...)`.
 
 ## Development

{agentshim-0.3.0 → agentshim-0.4.0}/agentshim/__init__.py

@@ -2,6 +2,7 @@ from .base import BaseAgentSession, BaseCodingAgent, CodingAgent, get_provider_c
 from .claude import ClaudeCodeCodingAgent
 from .copilot import CopilotCodingAgent
 from .codex import CodexCodingAgent
+from .events import CompositeEventHandler, ConsoleEventHandler, NullEventHandler
 from .gemini import GeminiCodingAgent
 from .mcp_config import HttpMcpServer, McpServerConfig, StdioMcpServer
 from .opencode import OpencodeCodingAgent
@@ -14,6 +15,9 @@ __all__ = [
     "get_provider_class",
     "list_providers",
     "register_provider",
+    "CompositeEventHandler",
+    "ConsoleEventHandler",
+    "NullEventHandler",
     "CopilotCodingAgent",
     "CodexCodingAgent",
     "GeminiCodingAgent",

{agentshim-0.3.0 → agentshim-0.4.0}/agentshim/base.py

@@ -9,7 +9,6 @@ from typing import Any, TypeVar
 from agentshim.events import AgentEventHandler
 from agentshim.mcp_config import McpServerConfig
 from agentshim.sandbox import SandboxConfig
-from agentshim.trajectory import NullTrajectoryRecorder, TrajectoryRecorderProtocol
 
 _T = TypeVar("_T")
 _READABLE_NAME_BOUNDARY = re.compile(r"(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])")
@@ -28,7 +27,6 @@ def _readable_name_from_class_name(class_name: str) -> str:
 class BaseCodingAgent(ABC):
     """Abstract base class for coding agents."""
 
-    recorder: TrajectoryRecorderProtocol = NullTrajectoryRecorder()
     event_handler: Any | None = None
 
     @property
@@ -113,9 +111,7 @@ class ProviderRegistry:
         if not normalized:
             raise ValueError("provider name must not be empty")
         if not _PROVIDER_NAME_PATTERN.fullmatch(normalized):
-            raise ValueError(
-                f"invalid provider name '{name}'; use lowercase letters, digits, hyphens, or underscores"
-            )
+            raise ValueError(f"invalid provider name '{name}'; use lowercase letters, digits, hyphens, or underscores")
         return normalized
 
     def _normalize_names(self, canonical_name: str, aliases: tuple[str, ...]) -> tuple[str, tuple[str, ...]]:
@@ -147,9 +143,7 @@ class ProviderRegistry:
         all_names = (canonical, *normalized_aliases)
 
         collisions = [
-            name
-            for name in all_names
-            if name in self._providers and self._providers[name] is not provider_cls
+            name for name in all_names if name in self._providers and self._providers[name] is not provider_cls
         ]
         if collisions and not overwrite:
             raise ValueError(
@@ -172,18 +166,14 @@ class ProviderRegistry:
         normalized = self._normalize_name(name)
         provider_cls = self._providers.get(normalized)
         if provider_cls is None:
-            raise ValueError(
-                f"Unknown coding agent provider '{name}'. Available providers: {self.list_providers()}"
-            )
+            raise ValueError(f"Unknown coding agent provider '{name}'. Available providers: {self.list_providers()}")
         return provider_cls
 
     def get_canonical_name(self, name: str) -> str:
         normalized = self._normalize_name(name)
         canonical = self._canonical_names.get(normalized)
         if canonical is None:
-            raise ValueError(
-                f"Unknown coding agent provider '{name}'. Available providers: {self.list_providers()}"
-            )
+            raise ValueError(f"Unknown coding agent provider '{name}'. Available providers: {self.list_providers()}")
         return canonical
 
 
@@ -243,8 +233,8 @@ class CodingAgent(BaseCodingAgent):
         self,
         provider: str,
         model: str | None = None,
-        recorder: TrajectoryRecorderProtocol | None = None,
         event_handler: AgentEventHandler | None = None,
+        event_handlers: Sequence[AgentEventHandler] | None = None,
         mcp_servers: Sequence[McpServerConfig] | None = None,
         sandbox: bool | SandboxConfig | None = False,
         backend_kwargs: dict[str, Any] | None = None,
@@ -256,10 +246,10 @@ class CodingAgent(BaseCodingAgent):
         portable_kwargs: dict[str, Any] = {}
         if model is not None:
             portable_kwargs["model"] = model
-        if recorder is not None:
-            portable_kwargs["recorder"] = recorder
         if event_handler is not None:
             portable_kwargs["event_handler"] = event_handler
+        if event_handlers is not None:
+            portable_kwargs["event_handlers"] = list(event_handlers)
         if mcp_servers is not None:
             portable_kwargs["mcp_servers"] = list(mcp_servers)
         if sandbox is not None and sandbox is not False:
@@ -269,8 +259,7 @@ class CodingAgent(BaseCodingAgent):
         overlapping_keys = sorted(portable_kwargs.keys() & advanced_kwargs.keys())
         if overlapping_keys:
             raise ValueError(
-                "backend_kwargs must not override portable CodingAgent arguments: "
-                + ", ".join(overlapping_keys)
+                "backend_kwargs must not override portable CodingAgent arguments: " + ", ".join(overlapping_keys)
             )
 
         self._backend: BaseCodingAgent = provider_cls(**portable_kwargs, **advanced_kwargs)
@@ -296,14 +285,6 @@ class CodingAgent(BaseCodingAgent):
     def model(self, value: Any) -> None:
         self._backend.model = value  # type: ignore[attr-defined]
 
-    @property
-    def recorder(self) -> TrajectoryRecorderProtocol:
-        return self._backend.recorder
-
-    @recorder.setter
-    def recorder(self, value: TrajectoryRecorderProtocol) -> None:
-        self._backend.recorder = value
-
     @property
     def event_handler(self) -> Any | None:
         return getattr(self._backend, "event_handler", None)

{agentshim-0.3.0 → agentshim-0.4.0}/agentshim/claude/agent.py

@@ -1,11 +1,9 @@
 import json
 import subprocess
 import time
-from collections.abc import Callable
+from collections.abc import Callable, Iterable
 from typing import Any
 
-from agentshim.trajectory import TrajectoryRecorderProtocol
-
 from ..base import register_provider
 from ..cli_agent import CLICodingAgent, CLIGenerationSession
 from ..events import AgentEventHandler
@@ -44,24 +42,22 @@ class ClaudeGenerationSession(CLIGenerationSession):
         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
+            if line.rstrip():
+                self.event_handler.on_thinking(line.rstrip() + "\n")
 
     def _handle_event(self, event: ClaudeEvent):
         """Handle a single parsed Claude event."""
         if isinstance(event, MultiEvent):
+            if event.usage and self.event_handler is not None:
+                on_usage = getattr(self.event_handler, "on_usage", None)
+                if on_usage is not None:
+                    on_usage(event.usage)
             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):
@@ -88,14 +84,7 @@ class ClaudeGenerationSession(CLIGenerationSession):
 
                 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,
@@ -105,6 +94,9 @@ class ClaudeGenerationSession(CLIGenerationSession):
 
         elif isinstance(event, ResultEvent):
             self.final_result = event.result
+            self.final_usage = event.usage
+            self.total_cost_usd = event.total_cost_usd
+            self.duration_ms = event.duration_ms
             # Anthropic reports cache_creation + cache_read as disjoint
             # from input_tokens; fold them into input_tokens to match the
             # crucible invariant (cached ⊆ input).
@@ -121,20 +113,6 @@ class ClaudeGenerationSession(CLIGenerationSession):
                 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)
@@ -150,8 +128,8 @@ class ClaudeCodeCodingAgent(CLICodingAgent):
     def __init__(
         self,
         model: str | None = None,
-        recorder: TrajectoryRecorderProtocol | None = None,
         event_handler: AgentEventHandler | None = None,
+        event_handlers: Iterable[AgentEventHandler] | None = None,
         mcp_servers: list[McpServerConfig] | None = None,
         sandbox: bool | SandboxConfig = False,
     ):
@@ -159,7 +137,6 @@ class ClaudeCodeCodingAgent(CLICodingAgent):
 
         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
@@ -169,7 +146,7 @@ class ClaudeCodeCodingAgent(CLICodingAgent):
                 sandboxed; the Claude process itself is not wrapped.
                 Defaults to False (no sandbox).
         """
-        super().__init__("claude", model, recorder, event_handler, mcp_servers)
+        super().__init__("claude", model, event_handler, event_handlers, 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
@@ -246,7 +223,6 @@ class ClaudeCodeCodingAgent(CLICodingAgent):
         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(
@@ -258,7 +234,6 @@ class ClaudeCodeCodingAgent(CLICodingAgent):
             cwd=cwd,
             timeout=timeout,
             silent=silent,
-            recorder=recorder,
             event_handler=self.event_handler,
             on_process_started=on_process_started,
         )

{agentshim-0.3.0 → agentshim-0.4.0}/agentshim/claude/events.py

@@ -1,18 +1,11 @@
 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):
+class ClaudeEvent:
     """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."""
@@ -36,7 +29,8 @@ class ClaudeEvent(ABC):
                             parameters=block.get("input"),
                         )
                     )
-            return MultiEvent(events) if events else None
+            usage = message.get("usage")
+            return MultiEvent(events, usage=usage) if events else None
         if event_type == "user":
             message = data.get("message", {})
             content_blocks = message.get("content", [])
@@ -53,6 +47,7 @@ class ClaudeEvent(ABC):
                 num_turns=data.get("num_turns"),
                 usage=data.get("usage"),
                 total_cost_usd=data.get("total_cost_usd"),
+                duration_ms=data.get("duration_ms"),
             )
 
         return None
@@ -61,12 +56,13 @@ class ClaudeEvent(ABC):
 class MultiEvent(ClaudeEvent):
     """Container for multiple events from a single message."""
 
-    def __init__(self, events: list[ClaudeEvent]):
+    def __init__(
+        self,
+        events: list[ClaudeEvent],
+        usage: dict[str, Any] | None = None,
+    ):
         self.events = events
-
-    def render(self, log_prefix: str) -> str | None:
-        # MultiEvent doesn't render itself; events are handled individually
-        return None
+        self.usage = usage
 
 
 class SystemEvent(ClaudeEvent):
@@ -80,10 +76,6 @@ class SystemEvent(ClaudeEvent):
         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."""
@@ -91,10 +83,6 @@ class TextEvent(ClaudeEvent):
     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."""
@@ -104,10 +92,6 @@ class ToolUseEvent(ClaudeEvent):
         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."""
@@ -122,12 +106,6 @@ class ToolResultEvent(ClaudeEvent):
         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."""
@@ -138,12 +116,10 @@ class ResultEvent(ClaudeEvent):
         num_turns: int | None = None,
         usage: dict[str, Any] | None = None,
         total_cost_usd: float | None = None,
+        duration_ms: int | 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
+        self.duration_ms = duration_ms