agentshim 0.5.0__tar.gz → 0.5.1__tar.gz

{agentshim-0.5.0 → agentshim-0.5.1}/.github/workflows/ci.yml

@@ -20,7 +20,22 @@ jobs:
         with:
           python-version: "3.11"
       - run: uv sync --locked --dev
-      - run: uv run ruff check .
+      - run: bash scripts/format_code.sh --check
+      - run: bash scripts/check_errors.sh
+
+  typecheck:
+    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: bash scripts/type_check.sh
 
   test:
     runs-on: ubuntu-latest

agentshim-0.5.1/.github/workflows/docs.yml

@@ -0,0 +1,52 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    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 --group docs
+      - run: uv run mkdocs build --strict --site-dir site
+
+      - name: Upload Pages artifact
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    concurrency:
+      group: pages
+      cancel-in-progress: false
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/configure-pages@v5
+      - id: deployment
+        uses: actions/deploy-pages@v4

{agentshim-0.5.0 → agentshim-0.5.1}/.gitignore

@@ -4,3 +4,4 @@ __pycache__/
 .ruff_cache/
 dist/
 build/
+site/

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentshim
-Version: 0.5.0
+Version: 0.5.1
 Summary: Provider-agnostic coding-agent CLI shims
 Requires-Python: >=3.10
 Requires-Dist: litellm>=1.0.0
@@ -342,6 +342,9 @@ Notes:
 
 ```bash
 uv sync --dev
+bash scripts/format_code.sh --check
+bash scripts/check_errors.sh
+bash scripts/type_check.sh
 uv run pytest
 ```
 

{agentshim-0.5.0 → agentshim-0.5.1}/README.md

@@ -331,6 +331,9 @@ Notes:
 
 ```bash
 uv sync --dev
+bash scripts/format_code.sh --check
+bash scripts/check_errors.sh
+bash scripts/type_check.sh
 uv run pytest
 ```
 

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

@@ -3,13 +3,15 @@ from __future__ import annotations
 import inspect
 import re
 from abc import ABC, abstractmethod
-from collections.abc import Callable, Sequence
-from typing import Any, TypeVar
+from typing import TYPE_CHECKING, Any, TypeVar, cast
 
-from agentshim.events import AgentEventHandler
-from agentshim.executor import CommandExecutor, CommandHandle
-from agentshim.mcp_config import McpServerConfig
-from agentshim.sandbox import SandboxConfig
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+
+    from agentshim.events import AgentEventHandler
+    from agentshim.executor import CommandExecutor, CommandHandle
+    from agentshim.mcp_config import McpServerConfig
+    from agentshim.sandbox import SandboxConfig
 
 _T = TypeVar("_T")
 _READABLE_NAME_BOUNDARY = re.compile(r"(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])")
@@ -105,7 +107,7 @@ class ProviderRegistry:
         self._providers: dict[str, ProviderClass] = {}
         self._canonical_names: dict[str, str] = {}
 
-    def _normalize_name(self, name: str) -> str:
+    def _normalize_name(self, name: object) -> str:
         if not isinstance(name, str):
             raise TypeError(f"provider name must be a string, got {type(name).__name__}")
         normalized = name.strip().lower()
@@ -122,6 +124,9 @@ class ProviderRegistry:
         )
         return canonical, normalized_aliases
 
+    def validate_names(self, canonical_name: str, aliases: tuple[str, ...]) -> None:
+        self._normalize_names(canonical_name, aliases)
+
     def _validate_provider_class(self, cls: type[Any]) -> ProviderClass:
         if not inspect.isclass(cls):
             raise TypeError(f"registered provider must be a class, got {type(cls).__name__}")
@@ -200,14 +205,17 @@ def register_provider(
     """
 
     all_aliases = (*extra_names, *aliases)
-    _PROVIDER_REGISTRY._normalize_names(canonical_name, all_aliases)
+    _PROVIDER_REGISTRY.validate_names(canonical_name, all_aliases)
 
     def decorator(cls: type[_T]) -> type[_T]:
-        return _PROVIDER_REGISTRY.register(
-            cls,
-            canonical_name=canonical_name,
-            aliases=all_aliases,
-            overwrite=overwrite,
+        return cast(
+            "type[_T]",
+            _PROVIDER_REGISTRY.register(
+                cls,
+                canonical_name=canonical_name,
+                aliases=all_aliases,
+                overwrite=overwrite,
+            ),
         )
 
     return decorator
@@ -297,6 +305,17 @@ class CodingAgent(BaseCodingAgent):
     def event_handler(self, value: Any | None) -> None:
         self._backend.event_handler = value
 
+    @property
+    def last_usage(self) -> Any:
+        """Token/turn usage from the backend's most recent ``generate``.
+
+        ``generate`` writes usage onto the concrete backend, so the
+        portable wrapper must surface it here — otherwise callers holding a
+        ``CodingAgent`` (rather than the raw provider class) read a missing
+        attribute and lose all usage accounting.
+        """
+        return getattr(self._backend, "last_usage", None)
+
     def start_session(
         self,
         cwd: str | None = None,

{agentshim-0.5.0 → agentshim-0.5.1}/agentshim/codex/agent.py

@@ -1,7 +1,7 @@
 import json
 import time
 from collections.abc import Callable, Iterable, Sequence
-from typing import Any
+from typing import Any, cast
 
 from ..base import register_provider
 from ..cli_agent import CLICodingAgent, CLIGenerationSession
@@ -22,6 +22,10 @@ from .events import (
 )
 
 
+def _tool_args(value: Any) -> dict[str, Any]:
+    return cast("dict[str, Any]", value) if isinstance(value, dict) else {}
+
+
 class CodexGenerationSession(CLIGenerationSession):
     """Session that parses Codex ``--json`` event stream."""
 
@@ -128,7 +132,7 @@ class CodexGenerationSession(CLIGenerationSession):
                 if event.tool_name is None:
                     return
                 event.tool_name_resolved = event.tool_name
-                args = event.parameters or {}
+                args = _tool_args(event.parameters)
                 duration = None
                 if self.event_handler:
                     self.event_handler.on_tool_call(event.tool_name, args)
@@ -140,7 +144,7 @@ class CodexGenerationSession(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, event.parameters or {})
+                args = _tool_args(self.tool_args.get(event.tool_id, event.parameters))
 
                 if event.tool_id not in self.tool_map and self.event_handler and event.tool_name:
                     self.event_handler.on_tool_call(event.tool_name, args)

{agentshim-0.5.0 → agentshim-0.5.1}/agentshim/codex/events.py

@@ -104,15 +104,6 @@ def _item_parameters(item: dict[str, Any]) -> dict[str, Any]:
     return {k: v for k, v in item.items() if k not in excluded}
 
 
-def _summarize_item(item: dict[str, Any]) -> str:
-    """Summarize a generic codex item for the tool-result output field."""
-    for key in ("text", "summary", "output", "result"):
-        value = item.get(key)
-        if isinstance(value, str) and value:
-            return value
-    return ""
-
-
 class ThreadStartedEvent(CodexEvent):
     """Thread-level start event carrying the resumable ``thread_id``."""
 

{agentshim-0.5.0 → agentshim-0.5.1}/agentshim/copilot/agent.py

@@ -2,15 +2,11 @@ from __future__ import annotations
 
 import json
 import time
-from collections.abc import Callable, Iterable, Sequence
-from typing import Any
+from typing import TYPE_CHECKING, Any, cast
 
 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
+from ..mcp_config import HttpMcpServer
 from ..usage import ProviderUsage, TokenUsage
 from .events import (
     CopilotEvent,
@@ -25,6 +21,14 @@ from .events import (
     UsageEvent,
 )
 
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable, Sequence
+
+    from ..events import AgentEventHandler
+    from ..executor import CommandExecutor, CommandHandle
+    from ..mcp_config import McpServerConfig
+    from ..sandbox import SandboxConfig
+
 
 class CopilotGenerationSession(CLIGenerationSession):
     """Session that parses Copilot CLI JSONL events."""
@@ -71,6 +75,7 @@ class CopilotGenerationSession(CLIGenerationSession):
 
         if not isinstance(data, dict):
             return
+        data = cast("dict[str, Any]", data)
 
         event = CopilotEvent.from_dict(data)
         if event is None:
@@ -165,10 +170,9 @@ class CopilotGenerationSession(CLIGenerationSession):
                 self.session_id = event.session_id
             return
 
-        if isinstance(event, ErrorEvent):
-            if event.message:
-                self.stdout_lines.append(event.message)
-                self.event_handler.on_thinking(f"[copilot error] {event.message}")
+        if isinstance(event, ErrorEvent) and event.message:
+            self.stdout_lines.append(event.message)
+            self.event_handler.on_thinking(f"[copilot error] {event.message}")
 
     def run(self, prompt: str) -> str:
         super().run(prompt)

{agentshim-0.5.0 → agentshim-0.5.1}/agentshim/copilot/events.py

@@ -20,8 +20,9 @@ def _extract_tool_result(result_raw: Any) -> tuple[str, int | None]:
 
     contents = result.get("contents")
     if isinstance(contents, list):
+        typed_contents = cast("list[Any]", contents)
         rendered_blocks: list[str] = []
-        for item_raw in contents:
+        for item_raw in typed_contents:
             item = _as_dict(item_raw)
             item_type = item.get("type")
             if item_type in ("text", "terminal"):

{agentshim-0.5.0 → agentshim-0.5.1}/agentshim/executor.py

@@ -1,14 +1,16 @@
 from __future__ import annotations
 
-import io
 import os
 import shutil
 import signal
 import subprocess
 import threading
-from collections.abc import Callable
 from dataclasses import dataclass
-from typing import Any, Protocol
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    import io
+    from collections.abc import Callable
 
 
 class CommandHandle(Protocol):
@@ -48,7 +50,7 @@ class CommandRequest:
     stdin: str
     cwd: str | None
     env: dict[str, str]
-    timeout: int | None
+    timeout: float | None
 
 
 @dataclass(frozen=True)
@@ -230,9 +232,7 @@ class HostCommandExecutor:
                     f"Stderr: {result.stderr}"
                 )
         except self._subprocess.TimeoutExpired as e:
-            raise RuntimeError(
-                f"CLI tool at '{binary_path}' did not respond to '--help' within {timeout}s."
-            ) from e
+            raise RuntimeError(f"CLI tool at '{binary_path}' did not respond to '--help' within {timeout}s.") from e
         except FileNotFoundError as e:
             raise RuntimeError(
                 f"CLI tool not found at '{binary_path}'. Please ensure it is installed and in your PATH."

agentshim-0.5.1/docs/api.md

@@ -0,0 +1,3 @@
+# API Reference
+
+::: agentshim

agentshim-0.5.1/docs/development.md

@@ -0,0 +1,27 @@
+# Development
+
+Install development dependencies and run the test suite with `uv`.
+
+```bash
+uv sync --dev
+uv run pytest
+```
+
+## Build Package
+
+```bash
+uv build
+```
+
+## Publish Package
+
+```bash
+uv publish
+```
+
+## Build Docs Locally
+
+```bash
+uv sync --group docs
+uv run mkdocs build --strict
+```

agentshim-0.5.1/docs/events.md

@@ -0,0 +1,137 @@
+# Events
+
+`agentshim` normalizes provider-specific streaming output into a small,
+portable event interface. Claude Code, Codex, Copilot, Gemini, and Opencode all
+emit different native event streams; the event handler API gives callers one
+place to observe the common concepts across those tools.
+
+Use events when you want to render live progress, capture tool activity, record
+usage, or connect agent runs to your own logging or tracing system without
+parsing each provider's CLI output yourself.
+
+## Portable Events
+
+Custom handlers can implement these common callbacks:
+
+| Event | Called when | Notes |
+| --- | --- | --- |
+| `on_thinking(text)` | The agent emits assistant text, reasoning/progress text, or other provider status text. | Text may arrive incrementally. Handlers should append or stream it rather than assuming one complete message per call. |
+| `on_tool_call(tool, args=None)` | The provider reports that the agent is starting or requesting a tool call. | `tool` is the provider's tool name. `args` is usually a dict, but can be a string or `None` when that is all the provider exposes. |
+| `on_tool_result(tool, stdout="", stderr="", exit_code=None, duration=None)` | The provider reports a completed tool result. | Providers vary in how much result metadata they expose, so handlers should tolerate missing `exit_code` and `duration`. |
+| `on_usage(usage)` | The provider reports per-turn token or usage information. | The payload is a normalized best-effort dict. Older handlers can omit this method. |
+
+These events are intentionally broad. They are not a lossless copy of every
+provider's native event schema; they are the stable interface for common
+observability and UI use cases across coding-agent CLIs.
+
+## Optional Runtime Hooks
+
+Some built-in handlers also understand lower-level runtime hooks:
+
+| Hook | Called when |
+| --- | --- |
+| `on_run_start(command)` | The underlying provider CLI command is about to start. |
+| `on_run_end(exit_code=None)` | The underlying provider CLI command has exited. |
+| `on_stderr(text)` | The provider process writes stderr that is not parsed as a structured provider event. |
+
+These hooks are useful for terminal renderers and debugging. They are optional:
+custom handlers focused on portable agent events can ignore them.
+
+## Default Console Output
+
+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:
+        print(text, end="")
+
+    def on_tool_call(self, tool: str, args: dict | str | None = None) -> None:
+        print(f"tool started: {tool} {args or ''}")
+
+    def on_tool_result(
+        self,
+        tool: str,
+        stdout: str = "",
+        stderr: str = "",
+        exit_code: int | None = None,
+        duration: float | None = None,
+    ) -> None:
+        output = stdout or stderr
+        print(f"tool finished: {tool} exit={exit_code} {output}")
+
+    def on_usage(self, usage: dict) -> None:
+        print(f"usage: {usage}")
+
+
+agent = CodingAgent(provider="claude", event_handler=MyHandler())
+agent.generate("Inspect this repository.")
+```
+
+You can implement only the events your application needs when the provider path
+checks for optional callbacks. For maximum compatibility across providers and
+handler composition, define all four portable event methods.
+
+```python
+class MinimalHandler:
+    def on_thinking(self, text: str) -> None:
+        ...
+
+    def on_tool_call(self, tool: str, args: dict | str | None = 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:
+        ...
+```
+
+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)
+```

agentshim-0.5.1/docs/executors.md

@@ -0,0 +1,82 @@
+# Executors
+
+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.

agentshim-0.5.1/docs/extending.md

@@ -0,0 +1,51 @@
+# Extending agentshim
+
+Advanced users can register their own providers. `CodingAgent(...)` keeps its
+main constructor portable; provider-specific constructor extras should go
+through `backend_kwargs`.
+
+```python
+from agentshim import BaseCodingAgent, CodingAgent, register_provider
+
+
+@register_provider("my-agent", aliases=("my-agent-dev",))
+class MyAgent(BaseCodingAgent):
+    def __init__(
+        self,
+        model: str | None = None,
+        region: str | None = None,
+        event_handler=None,
+        event_handlers=None,
+        mcp_servers=None,
+        sandbox=False,
+    ):
+        self.model = model
+        self.region = region
+        self.event_handler = event_handler
+
+    def generate(self, prompt: str, cwd=None, timeout=300, silent=False) -> str:
+        return f"handled: {prompt}"
+
+
+agent = CodingAgent(
+    provider="my-agent-dev",
+    model="demo",
+    backend_kwargs={"region": "us-west1"},
+)
+print(agent.generate("hello"))
+```
+
+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`, `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(...)`.