agentshim 0.15.1__tar.gz → 0.15.2__tar.gz

{agentshim-0.15.1 → agentshim-0.15.2}/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.15.2 (2026-10-09)
+
+### Added
+
+- `RateLimitStatus` event (also in `AgentEvent` and `ConsoleEventHandler`):
+  the provider's report of one rate-limit window, with `window`, `limit`,
+  `used_fraction`, `remaining_fraction`, `resets_at`, `window_minutes`,
+  `exhausted` and `raw`. Unstated values are `None`, never zero. Emitted by the
+  Claude stream transport and one-shot parser (`rate_limit_event`) and by the
+  Codex app-server transport (`account/rateLimits/updated`). Test doubles:
+  `ClaudePeerTurn(rate_limit=...)` and the `ReportRateLimits` Codex script step.
+- Provider readiness probe. `probe_provider(name, *, executor, confinement, env,
+  timeout)` and `Agent.probe()` return a `ProviderStatus` (`binary_found`,
+  `path`, `version`, `auth: AuthState`, `auth_detail`) without running a turn or
+  calling a model, through the executor and confinement a turn would use. Claude
+  uses `claude auth status`, Codex `codex login status`; Gemini, Copilot and
+  opencode have no status command and report `AuthState.UNKNOWN`. A missing
+  binary is a result, not an error. Test double `agentshim.testing.probe_executor`.
+- Mid-turn steering. `Session.steer(text)` (thread-safe) sends a message into the
+  running turn; `SteerableConversation` is the transport-tier protocol and
+  `ProviderProfile.supports_steer` the capability (true for the Claude and Codex
+  stream transports). It never queues: `ProviderCapabilityError` when
+  unsupported, new `NoRunningTurnError` (a `SessionStateError`) when no turn can
+  take it. Events `SteerDelivered`, `SteerConsumed`, `SteerRejected`.
+- Codex maps to `turn/steer`. Claude Code writes a user envelope and runs with
+  `--replay-user-messages`; `turn()` still returns one `TurnResult` when the CLI
+  queues the message as a follow-on turn (new `steer_grace_s` option).
+- Test doubles: `AwaitSteer` and `CodexScript(steer_refusal=)`,
+  `ClaudePeerTurn(injects_steer=)` and `ClaudeStreamPeers(drops_queued_messages=)`,
+  `fake_profile(supports_steer=)`, `FakeConversation.steer`, and
+  `SteerableConversationContract`.
+
 ## 0.15.1 (2026-10-09)
 
 ### Added

{agentshim-0.15.1 → agentshim-0.15.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentshim
-Version: 0.15.1
+Version: 0.15.2
 Summary: Provider-agnostic coding-agent CLI shims
 License-Expression: MIT
 License-File: LICENSE

{agentshim-0.15.1 → agentshim-0.15.2}/agentshim/__init__.py

@@ -15,6 +15,7 @@ from .core import (
     ApprovalPolicy,
     ArgvContext,
     AssistantText,
+    AuthState,
     Checkpoint,
     CheckpointStore,
     CliCheckError,
@@ -48,6 +49,7 @@ from .core import (
     NativeMode,
     NativePermissions,
     NoopInstallation,
+    NoRunningTurnError,
     NullEventHandler,
     OutputSchema,
     OutputSchemaStyle,
@@ -60,8 +62,10 @@ from .core import (
     ProviderCapabilityError,
     ProviderError,
     ProviderProfile,
+    ProviderStatus,
     ProviderUsage,
     RandomIds,
+    RateLimitStatus,
     RawOutput,
     ReapError,
     Reasoning,
@@ -84,6 +88,10 @@ from .core import (
     SkillTracker,
     Stderr,
     StdioMcpServer,
+    SteerableConversation,
+    SteerConsumed,
+    SteerDelivered,
+    SteerRejected,
     StopSignal,
     StreamParser,
     SystemClock,
@@ -137,6 +145,7 @@ from .execution import (
     confine,
 )
 from .oneshot import OneShotTransport
+from .probe import probe_provider
 from .providers import get_provider, provider_names
 from .providers.claude import ClaudeHook, ClaudeProvider, ClaudeStreamTransport, SandboxConfig
 from .providers.codex import CodexProvider, CodexSandboxConfig
@@ -147,7 +156,7 @@ from .providers.opencode import OpencodeProvider
 from .runtime import Agent
 from .session import Session, Turn, TurnTicket, map_mcp_servers
 
-__version__ = "0.15.1"
+__version__ = "0.15.2"
 
 __all__ = [
     "Agent",
@@ -159,6 +168,7 @@ __all__ = [
     "ApprovalPolicy",
     "ArgvContext",
     "AssistantText",
+    "AuthState",
     "CallbackCommandStreamSink",
     "Checkpoint",
     "CheckpointStore",
@@ -210,6 +220,7 @@ __all__ = [
     "ModelPricing",
     "NativeMode",
     "NativePermissions",
+    "NoRunningTurnError",
     "NoopInstallation",
     "NullEventHandler",
     "NullSink",
@@ -229,8 +240,10 @@ __all__ = [
     "ProviderCapabilityError",
     "ProviderError",
     "ProviderProfile",
+    "ProviderStatus",
     "ProviderUsage",
     "RandomIds",
+    "RateLimitStatus",
     "RawOutput",
     "ReapError",
     "Reasoning",
@@ -258,6 +271,10 @@ __all__ = [
     "StderrLine",
     "StdioMcpServer",
     "StdoutLine",
+    "SteerConsumed",
+    "SteerDelivered",
+    "SteerRejected",
+    "SteerableConversation",
     "StopSignal",
     "StreamParser",
     "SystemClock",
@@ -295,5 +312,6 @@ __all__ = [
     "parse_json_object",
     "prepare_config_home",
     "price_for",
+    "probe_provider",
     "provider_names",
 ]

{agentshim-0.15.1 → agentshim-0.15.2}/agentshim/core/__init__.py

@@ -9,7 +9,13 @@ from __future__ import annotations
 
 from .checkpoints import Checkpoint, CheckpointStore, InMemoryCheckpointStore
 from .clock import Clock, StopSignal, SystemClock
-from .conversation import Conversation, ConversationSpec, Transport, TransportKind
+from .conversation import (
+    Conversation,
+    ConversationSpec,
+    SteerableConversation,
+    Transport,
+    TransportKind,
+)
 from .env import interactive_env
 from .errors import (
     AgentShimError,
@@ -20,6 +26,7 @@ from .errors import (
     ContinuityError,
     FailureKind,
     McpConfigError,
+    NoRunningTurnError,
     ProcessClosedError,
     ProviderCapabilityError,
     ReapError,
@@ -41,6 +48,7 @@ from .events import (
     Lifecycle,
     NullEventHandler,
     ProviderError,
+    RateLimitStatus,
     RawOutput,
     Reasoning,
     RunFinished,
@@ -49,6 +57,9 @@ from .events import (
     SkillInvoked,
     SkillsDiscovered,
     Stderr,
+    SteerConsumed,
+    SteerDelivered,
+    SteerRejected,
     ToolCall,
     ToolResult,
     TurnInterrupted,
@@ -92,6 +103,7 @@ from .provider import (
 from .schema import compact_json, dialect_problems, materialize, normalize
 from .session_policy import Continuity, PolicyConfig, RetryPolicy, SessionPolicy, SessionState
 from .skills import SkillSummary, SkillTracker
+from .status import AuthState, ProviderStatus
 from .stream import ToolTracker, parse_json_object
 from .turn import OutputSchema, TurnRequest, TurnResult
 from .usage import ProviderUsage, TokenUsage, TokenWeights, normalized_usage
@@ -104,6 +116,7 @@ __all__ = [
     "ApprovalPolicy",
     "ArgvContext",
     "AssistantText",
+    "AuthState",
     "Checkpoint",
     "CheckpointStore",
     "CliCheckError",
@@ -136,6 +149,7 @@ __all__ = [
     "ModelPricing",
     "NativeMode",
     "NativePermissions",
+    "NoRunningTurnError",
     "NoopInstallation",
     "NullEventHandler",
     "OutputSchema",
@@ -149,8 +163,10 @@ __all__ = [
     "ProviderCapabilityError",
     "ProviderError",
     "ProviderProfile",
+    "ProviderStatus",
     "ProviderUsage",
     "RandomIds",
+    "RateLimitStatus",
     "RawOutput",
     "ReapError",
     "Reasoning",
@@ -173,6 +189,10 @@ __all__ = [
     "SkillsDiscovered",
     "Stderr",
     "StdioMcpServer",
+    "SteerConsumed",
+    "SteerDelivered",
+    "SteerRejected",
+    "SteerableConversation",
     "StopSignal",
     "StreamParser",
     "SystemClock",

{agentshim-0.15.1 → agentshim-0.15.2}/agentshim/core/conversation.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from enum import Enum
-from typing import TYPE_CHECKING, Protocol
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
 
 from .profile import ConfigScope, McpScope, SkillScope
 
@@ -96,6 +96,27 @@ class Conversation(Protocol):
         ...
 
 
+@runtime_checkable
+class SteerableConversation(Conversation, Protocol):
+    """A conversation that accepts a message while a turn runs.
+
+    A transport whose profile has ``supports_steer`` opens conversations of
+    this kind. ``steer`` neither queues nor retries: the message goes to the
+    running turn now or the call raises.
+    """
+
+    def steer(self, text: str) -> None:
+        """Send *text* into the running turn. Thread-safe.
+
+        Raises ``NoRunningTurnError`` when no turn is running or the running
+        one cannot take a message yet (or any longer). Returns once the message
+        is on its way; the outcome is reported as ``SteerDelivered``,
+        ``SteerConsumed`` and ``SteerRejected`` events, on the thread running
+        the turn.
+        """
+        ...
+
+
 class Transport(Protocol):
     """A way to reach one provider, producing conversations."""
 

{agentshim-0.15.1 → agentshim-0.15.2}/agentshim/core/errors.py

@@ -227,6 +227,15 @@ class SessionStateError(AgentShimError):
     """
 
 
+class NoRunningTurnError(SessionStateError):
+    """``steer`` was called when no turn could take a message.
+
+    Either no turn is running, or the running one has not started yet or is
+    already finishing. agentshim never holds a steer back for a later turn: a
+    caller that wants one delivered later sends it with the next prompt.
+    """
+
+
 class TurnCancelledError(AgentShimError):
     """An interrupt arrived before the turn could start, so it never ran."""
 

{agentshim-0.15.1 → agentshim-0.15.2}/agentshim/core/events.py

@@ -8,7 +8,7 @@ the session sees it.
 from __future__ import annotations
 
 import sys
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
 
 if TYPE_CHECKING:
@@ -156,6 +156,83 @@ class ApprovalDenied:
     detail: str
 
 
+def _no_raw() -> Mapping[str, Any]:
+    return {}
+
+
+@dataclass(frozen=True)
+class RateLimitStatus:
+    """The provider's view of one rate-limit window, as it just reported it.
+
+    Optional: a provider that has no such signal emits nothing, and a field the
+    provider did not state is ``None``, never zero. One event describes one
+    window, so a provider that reports several (a five-hour and a weekly one)
+    emits several events. A consumer reads the newest event per
+    ``(limit, window)``.
+
+    ``window`` names the window in the provider's words (``five_hour``,
+    ``primary``). ``limit`` names the limit it belongs to when the provider
+    has more than one (Codex ``limit_id``). ``used_fraction`` is the share of
+    the window already used, ``0.0`` to ``1.0`` (it may exceed 1 when the
+    provider reports over-use). ``resets_at`` is epoch seconds.
+    ``exhausted`` is ``True`` when the provider says this limit is reached,
+    ``False`` when it says it is not, ``None`` when it does not say.
+    ``raw`` is the provider's own mapping, for diagnostics.
+    """
+
+    window: str | None
+    used_fraction: float | None
+    resets_at: float | None
+    limit: str | None = None
+    window_minutes: int | None = None
+    exhausted: bool | None = None
+    raw: Mapping[str, Any] = field(default_factory=_no_raw)
+
+    @property
+    def remaining_fraction(self) -> float | None:
+        """The share of the window still available, or ``None`` when usage is unknown."""
+        if self.used_fraction is None:
+            return None
+        return max(0.0, 1.0 - self.used_fraction)
+
+
+@dataclass(frozen=True)
+class SteerDelivered:
+    """A message sent with ``steer`` reached the provider, which accepted it.
+
+    This says the provider holds the message, not that the model has seen it
+    (see ``SteerConsumed``). Emitted on the thread running the turn.
+    """
+
+    text: str
+
+
+@dataclass(frozen=True)
+class SteerConsumed:
+    """The provider took a steered message into the running turn's context.
+
+    Emitted where the provider reports it: Codex when the message becomes an
+    item of the turn, Claude Code when it echoes the message back. A message
+    that the provider only queued for the next turn of its own (Claude Code,
+    when the model is not at a tool boundary) is consumed when that turn starts;
+    the steering turn then continues until that follow-on finishes.
+    """
+
+    text: str
+
+
+@dataclass(frozen=True)
+class SteerRejected:
+    """The provider refused a steered message; the turn is unaffected.
+
+    ``reason`` is the provider's own explanation. Codex refuses a steer for a
+    turn that cannot take one (a compaction, say) or that has just ended.
+    """
+
+    text: str
+    reason: str
+
+
 AgentEvent = (
     RunStarted
     | RunFinished
@@ -173,6 +250,10 @@ AgentEvent = (
     | ProviderError
     | TurnInterrupted
     | ApprovalDenied
+    | RateLimitStatus
+    | SteerDelivered
+    | SteerConsumed
+    | SteerRejected
 )
 
 
@@ -260,6 +341,19 @@ def _truncate_lines(content: str, max_lines: int = _TOOL_OUTPUT_MAX_LINES) -> st
     return content
 
 
+def _describe_rate_limit(event: RateLimitStatus) -> str:
+    """One console line for a rate-limit window; unknown parts are left out."""
+    name = " ".join(part for part in (event.limit, event.window) if part) or "rate limit"
+    parts = [f"[rate limit] {name}"]
+    if event.used_fraction is not None:
+        parts.append(f"{event.used_fraction:.0%} used")
+    if event.exhausted:
+        parts.append("reached")
+    if event.resets_at is not None:
+        parts.append(f"resets at epoch {event.resets_at:.0f}")
+    return ", ".join(parts)
+
+
 class ConsoleEventHandler:
     """Render events as human-readable lines on a text stream.
 
@@ -392,6 +486,14 @@ class ConsoleEventHandler:
         else:
             self._line(self._paint(f"{event.tool} ran successfully", colour))
 
+    def _render_steer(self, event: SteerDelivered | SteerConsumed | SteerRejected) -> None:
+        if isinstance(event, SteerRejected):
+            self._line(f"[steer rejected] {event.text}: {event.reason}")
+        elif isinstance(event, SteerConsumed):
+            self._line(self._paint(f"[steer consumed] {event.text}", self._DIM))
+        else:
+            self._line(self._paint(f"[steer delivered] {event.text}", self._DIM))
+
     def _render_diagnostic(self, event: AgentEvent) -> None:
         """Write the tagged non-output events, and drop the rest.
 
@@ -408,5 +510,9 @@ class ConsoleEventHandler:
             self._line(self._paint("[interrupted]", self._DIM))
         elif isinstance(event, ApprovalDenied):
             self._line(f"[approval denied] {event.kind}: {event.detail}")
+        elif isinstance(event, RateLimitStatus):
+            self._line(self._paint(_describe_rate_limit(event), self._DIM))
+        elif isinstance(event, (SteerDelivered, SteerConsumed, SteerRejected)):
+            self._render_steer(event)
         elif isinstance(event, Lifecycle) and self._show_lifecycle:
             self._line(self._paint(f"[{event.kind}] {event.detail}", self._DIM))

{agentshim-0.15.1 → agentshim-0.15.2}/agentshim/core/profile.py

@@ -198,3 +198,7 @@ class ProviderProfile:
     #: When a session should retire a conversation of this provider; ``None``
     #: means never.
     renewal: RenewalBudget | None = None
+    #: Whether a conversation on this provider takes ``steer(text)`` while a
+    #: turn runs. A provider that does not (every one-shot transport) rejects
+    #: it with ``ProviderCapabilityError`` instead of delaying the message.
+    supports_steer: bool = False

agentshim-0.15.2/agentshim/core/status.py

@@ -0,0 +1,110 @@
+"""Provider readiness: what a probe reports, and how a provider declares its checks.
+
+A probe answers "could a turn start?" without running one: is the binary
+there, which version is it, is it logged in. It never calls a model. The
+answer is a ``ProviderStatus``; each provider declares its own checks as a
+``ProbeSpec``, and ``agentshim.probe`` runs them through an executor.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+
+
+class AuthState(str, Enum):
+    """Whether the provider CLI is authenticated, as far as its own tooling can say.
+
+    ``UNKNOWN`` is distinct from ``FAILED``: it means the CLI offers no cheap
+    way to tell (or the check itself could not run), so a caller must not
+    treat it as a problem.
+    """
+
+    KNOWN_OK = "known_ok"
+    FAILED = "failed"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True)
+class ProviderStatus:
+    """The readiness of one provider CLI on one executor.
+
+    ``version`` is ``None`` when the binary is missing or did not report one.
+    ``auth_detail`` explains ``auth`` in words fit for a log or an error
+    message, including the fix when authentication failed.
+    """
+
+    provider: str
+    binary_found: bool
+    path: str | None
+    version: str | None
+    auth: AuthState
+    auth_detail: str
+
+
+@dataclass(frozen=True)
+class ProbeOutput:
+    """What a status command printed."""
+
+    returncode: int
+    stdout: str
+    stderr: str
+
+    @property
+    def text(self) -> str:
+        """Both streams, stdout first."""
+        return self.stdout + self.stderr
+
+
+@dataclass(frozen=True)
+class AuthCheck:
+    """A provider's reading of its status command's output."""
+
+    state: AuthState
+    detail: str
+
+
+@dataclass(frozen=True)
+class AuthProbe:
+    """A cheap, non-model command that reports authentication, and how to read it.
+
+    ``argv`` follows the binary. ``read`` receives the output and the
+    environment the command ran with (an API key there changes what a failed
+    login means) and must return ``UNKNOWN`` for output it does not recognise
+    rather than guess.
+    """
+
+    argv: tuple[str, ...]
+    read: Callable[[ProbeOutput, Mapping[str, str]], AuthCheck]
+
+
+@dataclass(frozen=True)
+class ProbeSpec:
+    """A provider's readiness checks.
+
+    ``auth`` is ``None`` for a CLI with no status mechanism; ``auth_note`` then
+    says why the state is unknown.
+    """
+
+    auth: AuthProbe | None
+    auth_note: str = "this CLI has no authentication status command"
+    version_argv: tuple[str, ...] = ("--version",)
+
+
+_VERSION = re.compile(r"\d+(?:\.\d+)+(?:-[0-9A-Za-z.]+)?")
+
+
+def parse_version(text: str) -> str | None:
+    """The first dotted version number in *text*, or ``None``.
+
+    ``--version`` output varies (``2.1.295 (Claude Code)``,
+    ``codex-cli 0.160.0``, ``GitHub Copilot CLI 1.0.94.``); the number is the
+    only part every CLI shares.
+    """
+    match = _VERSION.search(text)
+    return match.group(0) if match else None

agentshim-0.15.2/agentshim/probe.py

@@ -0,0 +1,116 @@
+"""Readiness probe: is a provider CLI installed, which version, logged in?
+
+Composition layer, next to ``runtime``: it turns a provider name into the
+provider's declared checks and runs them on an executor. Everything runs
+through the executor and environment a turn would use, so a confinement or a
+container is probed where the agent would run. No check calls a model.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from agentshim.core.env import interactive_env
+from agentshim.core.errors import AgentShimError, CliNotFoundError
+from agentshim.core.status import (
+    AuthCheck,
+    AuthState,
+    ProbeOutput,
+    ProviderStatus,
+    parse_version,
+)
+from agentshim.execution.confinement import confine
+from agentshim.execution.executor import CommandRequest, NullSink
+from agentshim.execution.host import HostCommandExecutor
+from agentshim.providers import get_probe_spec, get_provider
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+    from agentshim.execution.confinement import Confinement
+    from agentshim.execution.executor import CommandExecutor
+
+
+def probe_provider(
+    provider: str,
+    *,
+    executor: CommandExecutor | None = None,
+    confinement: Confinement | None = None,
+    env: Mapping[str, str] | None = None,
+    timeout: float = 15.0,
+) -> ProviderStatus:
+    """Report the readiness of *provider* without running a turn.
+
+    Arguments mean what they mean for ``Agent``: *executor* defaults to the
+    local host, *confinement* wraps it and supplies the environment (so *env*
+    may not also be given), and *env* otherwise defaults to the login shell's
+    environment. *timeout* bounds each of the two commands (``--version`` and
+    the provider's status command).
+
+    A missing binary is a result (``binary_found=False``), not an error, so a
+    startup check can report every provider in one pass. A command that cannot
+    run or times out leaves that field unknown; it never raises for a CLI
+    problem. An unknown *provider* raises ``ValueError``.
+    """
+    base = executor if executor is not None else HostCommandExecutor()
+    if confinement is not None:
+        if env is not None:
+            msg = "env conflicts with confinement: the confinement supplies the agent environment"
+            raise ValueError(msg)
+        base = confine(base, confinement)
+        env = dict(confinement.env)
+    return probe_on(provider, base, dict(env) if env is not None else interactive_env(), timeout)
+
+
+def probe_on(
+    provider: str, executor: CommandExecutor, env: Mapping[str, str], timeout: float
+) -> ProviderStatus:
+    """Probe *provider* on an executor that is already confined, with the final *env*."""
+    profile = get_provider(provider).profile
+    spec = get_probe_spec(provider)
+    try:
+        path = executor.find_binary(profile.binary, env)
+    except CliNotFoundError:
+        detail = f"{profile.binary} was not found on PATH"
+        return ProviderStatus(
+            provider=provider,
+            binary_found=False,
+            path=None,
+            version=None,
+            auth=AuthState.UNKNOWN,
+            auth_detail=detail,
+        )
+
+    version_out = _run(executor, [path, *spec.version_argv], env, timeout)
+    version = None if version_out is None else parse_version(version_out.text)
+    if spec.auth is None:
+        check = AuthCheck(AuthState.UNKNOWN, spec.auth_note)
+    else:
+        auth_out = _run(executor, [path, *spec.auth.argv], env, timeout)
+        if auth_out is None:
+            check = AuthCheck(
+                AuthState.UNKNOWN,
+                f"`{profile.binary} {' '.join(spec.auth.argv)}` did not run or timed out",
+            )
+        else:
+            check = spec.auth.read(auth_out, env)
+    return ProviderStatus(
+        provider=provider,
+        binary_found=True,
+        path=path,
+        version=version,
+        auth=check.state,
+        auth_detail=check.detail,
+    )
+
+
+def _run(
+    executor: CommandExecutor, argv: Sequence[str], env: Mapping[str, str], timeout: float
+) -> ProbeOutput | None:
+    """Run one status command; ``None`` when it could not run or timed out."""
+    request = CommandRequest(argv=argv, stdin=None, cwd=None, env=env, timeout=timeout)
+    try:
+        result = executor.run(request, NullSink())
+    except (AgentShimError, OSError):
+        return None
+    return ProbeOutput(result.returncode, result.stdout, result.stderr)