agentshim 0.3.1__tar.gz → 0.5.0__tar.gz

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

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: uv sync --locked --dev
+      - run: uv run ruff check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --locked --dev
+      - run: uv run pytest

{agentshim-0.3.1 → agentshim-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentshim
-Version: 0.3.1
+Version: 0.5.0
 Summary: Provider-agnostic coding-agent CLI shims
 Requires-Python: >=3.10
 Requires-Dist: litellm>=1.0.0
@@ -22,10 +22,10 @@ prompting, session resumption, event parsing, or MCP configuration.
 - a shared CLI agent abstraction with a provider registry
 - adapters for Claude Code, Codex, Gemini, and Opencode
 - stateful chat sessions that automatically resume provider-native threads
+- injectable command executors for custom process launching or sandboxing
 - 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 +81,162 @@ 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. Run Commands Through a Custom Executor
+
+Provider classes accept an optional `executor=`. The executor controls binary
+lookup, CLI validation, and streaming process execution while `agentshim` keeps
+owning provider command construction, stdout/stderr parsing, session state, and
+event emission.
+
+This is useful when a caller needs to run the CLI somewhere other than the
+current host process, for example through an existing container, remote shell,
+or custom sandbox.
+
+```python
+from agentshim import (
+    CodexCodingAgent,
+    CommandHandle,
+    CommandRequest,
+    CommandResult,
+    CommandStreamSink,
+)
+
+
+class MyCommandHandle:
+    def terminate(self) -> None:
+        ...
+
+    def kill(self) -> None:
+        ...
+
+
+class MyExecutor:
+    def find_binary(self, binary_name: str, env: dict[str, str]) -> str:
+        # This value becomes request.argv[0]. Container or remote executors can
+        # return the binary name if lookup happens in the target runtime.
+        return binary_name
+
+    def check_binary(self, binary_path: str, env: dict[str, str], *, timeout: int) -> None:
+        # Raise RuntimeError if the target CLI is unavailable. No-op is fine
+        # when validation is not cheap or is handled by the runtime.
+        return None
+
+    def run(self, request: CommandRequest, sink: CommandStreamSink) -> CommandResult:
+        handle = MyCommandHandle()
+        sink.started(handle)
+
+        stdout = ""
+        stderr = ""
+
+        # Run request.argv in your target runtime, with request.stdin,
+        # request.cwd, request.env, and request.timeout. Stream each complete
+        # line as it arrives, preserving trailing newlines when present.
+        line = "streamed output\n"
+        stdout += line
+        sink.stdout(line)
+
+        return CommandResult(returncode=0, stdout=stdout, stderr=stderr)
+
+
+agent = CodexCodingAgent(executor=MyExecutor())
+```
+
+The default `HostCommandExecutor` preserves the normal local `subprocess`
+behavior. `CodingAgent(provider=..., executor=...)` forwards the same executor
+to the selected provider.
+
+Executor contract:
+
+- `CommandRequest.argv` is the complete provider CLI command. `argv[0]` is the
+  value returned by `find_binary`.
+- `CommandRequest.stdin` is the prompt text to write to the command's standard
+  input, then stdin should be closed.
+- `CommandRequest.cwd`, `env`, and `timeout` should be honored by the executor.
+- Call `sink.started(handle)` once after the command starts. The handle only
+  needs `terminate()` and `kill()`.
+- Call `sink.stdout(line)` and `sink.stderr(line)` as output is produced. Lines
+  should include trailing newlines when the underlying stream provided them.
+- Return `CommandResult(returncode, stdout, stderr)` after the command exits.
+  The returned text should match what was streamed through the sink.
+
+If you were using the pre-0.5 executor preview, replace
+`run_streaming(cmd, ..., on_stdout, on_stderr, on_process_started)` with
+`run(request, sink)`. The parser/event APIs remain internal; custom executors
+only provide a stable command runtime.
+
+### 4. Instantiate a Specific Provider Directly
 
 If you already know which backend you want, construct the provider class
 yourself.
@@ -103,7 +258,7 @@ The bundled provider classes are:
 - `GeminiCodingAgent`
 - `OpencodeCodingAgent`
 
-### 3. Configure MCP Servers
+### 5. Configure MCP Servers
 
 Claude Code and Codex can be configured with MCP servers by passing
 `HttpMcpServer` and `StdioMcpServer` objects at construction time.
@@ -154,14 +309,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 +335,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`, `sandbox`, and `executor` 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.1 → agentshim-0.5.0}/README.md

@@ -11,10 +11,10 @@ prompting, session resumption, event parsing, or MCP configuration.
 - a shared CLI agent abstraction with a provider registry
 - adapters for Claude Code, Codex, Gemini, and Opencode
 - stateful chat sessions that automatically resume provider-native threads
+- injectable command executors for custom process launching or sandboxing
 - 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 +70,162 @@ 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. Run Commands Through a Custom Executor
+
+Provider classes accept an optional `executor=`. The executor controls binary
+lookup, CLI validation, and streaming process execution while `agentshim` keeps
+owning provider command construction, stdout/stderr parsing, session state, and
+event emission.
+
+This is useful when a caller needs to run the CLI somewhere other than the
+current host process, for example through an existing container, remote shell,
+or custom sandbox.
+
+```python
+from agentshim import (
+    CodexCodingAgent,
+    CommandHandle,
+    CommandRequest,
+    CommandResult,
+    CommandStreamSink,
+)
+
+
+class MyCommandHandle:
+    def terminate(self) -> None:
+        ...
+
+    def kill(self) -> None:
+        ...
+
+
+class MyExecutor:
+    def find_binary(self, binary_name: str, env: dict[str, str]) -> str:
+        # This value becomes request.argv[0]. Container or remote executors can
+        # return the binary name if lookup happens in the target runtime.
+        return binary_name
+
+    def check_binary(self, binary_path: str, env: dict[str, str], *, timeout: int) -> None:
+        # Raise RuntimeError if the target CLI is unavailable. No-op is fine
+        # when validation is not cheap or is handled by the runtime.
+        return None
+
+    def run(self, request: CommandRequest, sink: CommandStreamSink) -> CommandResult:
+        handle = MyCommandHandle()
+        sink.started(handle)
+
+        stdout = ""
+        stderr = ""
+
+        # Run request.argv in your target runtime, with request.stdin,
+        # request.cwd, request.env, and request.timeout. Stream each complete
+        # line as it arrives, preserving trailing newlines when present.
+        line = "streamed output\n"
+        stdout += line
+        sink.stdout(line)
+
+        return CommandResult(returncode=0, stdout=stdout, stderr=stderr)
+
+
+agent = CodexCodingAgent(executor=MyExecutor())
+```
+
+The default `HostCommandExecutor` preserves the normal local `subprocess`
+behavior. `CodingAgent(provider=..., executor=...)` forwards the same executor
+to the selected provider.
+
+Executor contract:
+
+- `CommandRequest.argv` is the complete provider CLI command. `argv[0]` is the
+  value returned by `find_binary`.
+- `CommandRequest.stdin` is the prompt text to write to the command's standard
+  input, then stdin should be closed.
+- `CommandRequest.cwd`, `env`, and `timeout` should be honored by the executor.
+- Call `sink.started(handle)` once after the command starts. The handle only
+  needs `terminate()` and `kill()`.
+- Call `sink.stdout(line)` and `sink.stderr(line)` as output is produced. Lines
+  should include trailing newlines when the underlying stream provided them.
+- Return `CommandResult(returncode, stdout, stderr)` after the command exits.
+  The returned text should match what was streamed through the sink.
+
+If you were using the pre-0.5 executor preview, replace
+`run_streaming(cmd, ..., on_stdout, on_stderr, on_process_started)` with
+`run(request, sink)`. The parser/event APIs remain internal; custom executors
+only provide a stable command runtime.
+
+### 4. Instantiate a Specific Provider Directly
 
 If you already know which backend you want, construct the provider class
 yourself.
@@ -92,7 +247,7 @@ The bundled provider classes are:
 - `GeminiCodingAgent`
 - `OpencodeCodingAgent`
 
-### 3. Configure MCP Servers
+### 5. Configure MCP Servers
 
 Claude Code and Codex can be configured with MCP servers by passing
 `HttpMcpServer` and `StdioMcpServer` objects at construction time.
@@ -143,14 +298,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 +324,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`, `sandbox`, and `executor` 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.1 → agentshim-0.5.0}/agentshim/__init__.py

@@ -2,6 +2,16 @@ 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 .executor import (
+    CallbackCommandStreamSink,
+    CommandExecutor,
+    CommandHandle,
+    CommandRequest,
+    CommandResult,
+    CommandStreamSink,
+    HostCommandExecutor,
+)
 from .gemini import GeminiCodingAgent
 from .mcp_config import HttpMcpServer, McpServerConfig, StdioMcpServer
 from .opencode import OpencodeCodingAgent
@@ -14,6 +24,16 @@ __all__ = [
     "get_provider_class",
     "list_providers",
     "register_provider",
+    "CompositeEventHandler",
+    "ConsoleEventHandler",
+    "NullEventHandler",
+    "CallbackCommandStreamSink",
+    "CommandExecutor",
+    "CommandHandle",
+    "CommandRequest",
+    "CommandResult",
+    "CommandStreamSink",
+    "HostCommandExecutor",
     "CopilotCodingAgent",
     "CodexCodingAgent",
     "GeminiCodingAgent",

{agentshim-0.3.1 → agentshim-0.5.0}/agentshim/base.py

@@ -7,9 +7,9 @@ from collections.abc import Callable, Sequence
 from typing import Any, TypeVar
 
 from agentshim.events import AgentEventHandler
+from agentshim.executor import CommandExecutor, CommandHandle
 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 +28,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
@@ -85,7 +84,7 @@ class BaseAgentSession(ABC):
         cwd: str | None = None,
         timeout: int | None = None,
         silent: bool | None = None,
-        on_process_started: Callable[[Any], None] | None = None,
+        on_process_started: Callable[[CommandHandle], None] | None = None,
     ) -> str:
         """Send ``prompt`` within an existing chat session."""
 
@@ -113,9 +112,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 +144,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 +167,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
 
 
@@ -195,7 +186,7 @@ def register_provider(
     *extra_names: str,
     aliases: tuple[str, ...] = (),
     overwrite: bool = False,
-) -> Callable[[type[_T]], _T]:
+) -> Callable[[type[_T]], type[_T]]:
     """Decorator to register a coding agent provider.
 
     Registration is import-driven: the decorated class becomes available only
@@ -211,7 +202,7 @@ def register_provider(
     all_aliases = (*extra_names, *aliases)
     _PROVIDER_REGISTRY._normalize_names(canonical_name, all_aliases)
 
-    def decorator(cls: type[_T]) -> _T:
+    def decorator(cls: type[_T]) -> type[_T]:
         return _PROVIDER_REGISTRY.register(
             cls,
             canonical_name=canonical_name,
@@ -243,10 +234,11 @@ 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,
+        executor: CommandExecutor | None = None,
         backend_kwargs: dict[str, Any] | None = None,
     ) -> None:
         requested_provider = _PROVIDER_REGISTRY.get_canonical_name(provider)
@@ -256,21 +248,22 @@ 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:
             portable_kwargs["sandbox"] = sandbox
+        if executor is not None:
+            portable_kwargs["executor"] = executor
 
         advanced_kwargs = dict(backend_kwargs or {})
         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 +289,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)