agentshim 0.4.0__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.4.0 → agentshim-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentshim
-Version: 0.4.0
+Version: 0.5.0
 Summary: Provider-agnostic coding-agent CLI shims
 Requires-Python: >=3.10
 Requires-Dist: litellm>=1.0.0
@@ -22,6 +22,7 @@ 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
@@ -152,7 +153,90 @@ agent = CodingAgent(provider="claude")
 reply = agent.generate("Return only the answer.", silent=True)
 ```
 
-### 3. Instantiate a Specific Provider Directly
+### 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.
@@ -174,7 +258,7 @@ The bundled provider classes are:
 - `GeminiCodingAgent`
 - `OpencodeCodingAgent`
 
-### 4. 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.
@@ -251,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`, `event_handler`, `event_handlers`, `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.4.0 → agentshim-0.5.0}/README.md

@@ -11,6 +11,7 @@ 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
@@ -141,7 +142,90 @@ agent = CodingAgent(provider="claude")
 reply = agent.generate("Return only the answer.", silent=True)
 ```
 
-### 3. Instantiate a Specific Provider Directly
+### 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.
@@ -163,7 +247,7 @@ The bundled provider classes are:
 - `GeminiCodingAgent`
 - `OpencodeCodingAgent`
 
-### 4. 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.
@@ -240,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`, `event_handler`, `event_handlers`, `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.4.0 → agentshim-0.5.0}/agentshim/__init__.py

@@ -3,6 +3,15 @@ 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
@@ -18,6 +27,13 @@ __all__ = [
     "CompositeEventHandler",
     "ConsoleEventHandler",
     "NullEventHandler",
+    "CallbackCommandStreamSink",
+    "CommandExecutor",
+    "CommandHandle",
+    "CommandRequest",
+    "CommandResult",
+    "CommandStreamSink",
+    "HostCommandExecutor",
     "CopilotCodingAgent",
     "CodexCodingAgent",
     "GeminiCodingAgent",

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

@@ -7,6 +7,7 @@ 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
 
@@ -83,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."""
 
@@ -185,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
@@ -201,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,
@@ -237,6 +238,7 @@ class CodingAgent(BaseCodingAgent):
         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)
@@ -254,6 +256,8 @@ class CodingAgent(BaseCodingAgent):
             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())

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

@@ -1,12 +1,12 @@
 import json
-import subprocess
 import time
-from collections.abc import Callable, Iterable
+from collections.abc import Callable, Iterable, Sequence
 from typing import Any
 
 from ..base import register_provider
 from ..cli_agent import CLICodingAgent, CLIGenerationSession
 from ..events import AgentEventHandler
+from ..executor import CommandExecutor, CommandHandle
 from ..mcp_config import HttpMcpServer, McpServerConfig
 from ..sandbox import SandboxConfig, build_claude_sandbox_settings, resolve_sandbox
 from ..usage import ProviderUsage, TokenUsage
@@ -130,8 +130,9 @@ class ClaudeCodeCodingAgent(CLICodingAgent):
         model: str | None = None,
         event_handler: AgentEventHandler | None = None,
         event_handlers: Iterable[AgentEventHandler] | None = None,
-        mcp_servers: list[McpServerConfig] | None = None,
+        mcp_servers: Sequence[McpServerConfig] | None = None,
         sandbox: bool | SandboxConfig = False,
+        executor: CommandExecutor | None = None,
     ):
         """Initialize the Claude Code coding agent.
 
@@ -145,8 +146,9 @@ class ClaudeCodeCodingAgent(CLICodingAgent):
                 ``--settings``. Only bash subprocess commands are
                 sandboxed; the Claude process itself is not wrapped.
                 Defaults to False (no sandbox).
+            executor: Optional command executor for binary lookup and process execution.
         """
-        super().__init__("claude", model, event_handler, event_handlers, mcp_servers)
+        super().__init__("claude", model, event_handler, event_handlers, mcp_servers, executor=executor)
         self.sandbox = resolve_sandbox(sandbox)
         if self.sandbox is not None:
             # Without this, Claude Code cd's into a per-invocation scratch dir
@@ -223,7 +225,7 @@ class ClaudeCodeCodingAgent(CLICodingAgent):
         cwd: str | None = None,
         timeout: int = 300,
         silent: bool = False,
-        on_process_started: Callable[[subprocess.Popen[str]], None] | None = None,
+        on_process_started: Callable[[CommandHandle], None] | None = None,
     ) -> ClaudeGenerationSession:
         return ClaudeGenerationSession(
             binary_name=self.binary_name,
@@ -235,5 +237,6 @@ class ClaudeCodeCodingAgent(CLICodingAgent):
             timeout=timeout,
             silent=silent,
             event_handler=self.event_handler,
+            executor=self.executor,
             on_process_started=on_process_started,
         )