agentshim 0.19.0__tar.gz → 0.21.0__tar.gz

{agentshim-0.19.0 → agentshim-0.21.0}/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.21.0 (2026-10-18)
+
+### Added
+
+- `ModelSpec` ranks a model's generation among its vendor's: `generation_id` (`"5.5"`, shared
+  by every model of that generation), `generation` (`"Claude 5.5"`, `"GPT-6"`) and
+  `generation_rank` (`1` the newest). The three are set together, default to `None`, and are
+  filled for every shipped model. `ModelTable` rejects a vendor whose generations disagree on a
+  name or rank, or share a rank. Newest first: Claude 5.5, 5.1, 5, 4.8, 4.7, 4.6, 4.5; GPT-6.1,
+  6, 5.6, 5.5; Gemini 3.
+- `ProviderProfile.login` is a `LoginSpec`: the CLI's own command for a person to sign in
+  (`claude auth login`, `codex login` with `--device-auth` as its device variant,
+  `copilot login`, `opencode auth login`), and whether it needs a terminal.
+  `LoginSpec.command(binary, device=False)` is the full command line. Gemini CLI has no
+  sign-in command (`login` is `None`). Signed-in state stays in `ProbeSpec.auth` and
+  `probe_provider`.
+
+## 0.20.0 (2026-10-18)
+
+### Added
+
+- `ClaudeProvider(tools=ClaudeToolPolicy(...))`: run Claude Code with only the built-in tools
+  and allow rules the policy names, under `--permission-mode dontAsk`, instead of the
+  always-on `--dangerously-skip-permissions`. `ClaudeToolPolicy.only(["mcp__rs"])` gives a
+  turn no built-in tools and lets it call only that MCP server; `builtin=()` renders
+  `--tools ""`, and each allow rule is its own `--allowedTools` argument so a scoped rule
+  such as `Bash(git log:*)` arrives whole. A turn with an output schema also allows
+  `StructuredOutput`. Without a policy the argv is unchanged.
+
+### Changed
+
+- Provider integrations are resolved through an extensible `ProviderCatalog`; `CliAgent`,
+  `Agent`, `probe_provider` and the consumer test helpers take `catalog=` (#70).
+
 ## 0.19.0 (2026-10-17)
 
 ### Added

{agentshim-0.19.0 → agentshim-0.21.0}/PKG-INFO

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

{agentshim-0.19.0 → agentshim-0.21.0}/agentshim/__init__.py

@@ -29,6 +29,7 @@ from .core import (
     CompositeEventHandler,
     ConfigFileInstallation,
     ConfigScope,
+    ConnectionOptions,
     ConsoleEventHandler,
     ContextualStreamParser,
     Continuity,
@@ -50,15 +51,13 @@ from .core import (
     IdAllocator,
     InMemoryCheckpointStore,
     Lifecycle,
+    LoginSpec,
     McpConfigError,
     McpInstallation,
     McpMechanism,
     McpScope,
     McpServer,
     McpTransport,
-    ModelPricing,
-    ModelSpec,
-    ModelTable,
     NativeMode,
     NativePermissions,
     NoopInstallation,
@@ -69,7 +68,7 @@ from .core import (
     ParsedTurn,
     ParserContext,
     PolicyConfig,
-    PricingTable,
+    PricingContext,
     ProcessClosedError,
     Provider,
     ProviderCapabilityError,
@@ -126,22 +125,16 @@ from .core import (
     UsageReport,
     compact_json,
     compose_event_handlers,
-    context_window,
-    cost_usd,
-    default_models,
-    default_pricing,
     dialect_problems,
     host_auth_plan,
     install_config_file,
     interactive_env,
     materialize,
-    model_spec,
     normalize,
     normalized_usage,
     parse_json_object,
     plan_auth,
     prepare_config_home,
-    price_for,
 )
 from .execution import (
     CallbackCommandStreamSink,
@@ -164,10 +157,26 @@ from .execution import (
     TransformingExecutor,
     confine,
 )
+from .models import ModelSpec, ModelTable, context_window, default_models, model_spec
 from .oneshot import OneShotTransport
+from .pricing import ModelPricing, PricingTable, cost_usd, default_pricing, price_for
 from .probe import probe_provider
-from .providers import get_provider, provider_names, stream_provider_names
-from .providers.claude import ClaudeHook, ClaudeProvider, ClaudeStreamTransport, SandboxConfig
+from .providers import (
+    DEFAULT_CATALOG,
+    ProviderCatalog,
+    ProviderPlugin,
+    ProviderTestSupport,
+    get_provider,
+    provider_names,
+    stream_provider_names,
+)
+from .providers.claude import (
+    ClaudeHook,
+    ClaudeProvider,
+    ClaudeStreamTransport,
+    ClaudeToolPolicy,
+    SandboxConfig,
+)
 from .providers.codex import CodexProvider, CodexSandboxConfig
 from .providers.codex.app_server import CodexAppServerTransport
 from .providers.copilot import CopilotProvider
@@ -176,9 +185,9 @@ from .providers.opencode import OpencodeProvider
 from .runtime import Agent
 from .session import Session, Turn, TurnTicket, map_mcp_servers
 
-__version__ = "0.19.0"
+__version__ = "0.21.0"
 
-__all__ = [
+__all__ = [  # noqa: RUF022 - public API test uses Python's case-sensitive order
     "Agent",
     "AgentEvent",
     "AgentEventHandler",
@@ -198,6 +207,7 @@ __all__ = [
     "ClaudeHook",
     "ClaudeProvider",
     "ClaudeStreamTransport",
+    "ClaudeToolPolicy",
     "CliAgent",
     "CliCheckError",
     "CliExitError",
@@ -216,6 +226,7 @@ __all__ = [
     "ConfigFileInstallation",
     "ConfigScope",
     "Confinement",
+    "ConnectionOptions",
     "ConsoleEventHandler",
     "ContextualStreamParser",
     "Continuity",
@@ -225,6 +236,7 @@ __all__ = [
     "CopilotProvider",
     "CredentialKind",
     "CredentialSource",
+    "DEFAULT_CATALOG",
     "DockerExecConfinement",
     "EndpointSpec",
     "EnvCredential",
@@ -242,6 +254,7 @@ __all__ = [
     "IdAllocator",
     "InMemoryCheckpointStore",
     "Lifecycle",
+    "LoginSpec",
     "McpConfigError",
     "McpInstallation",
     "McpMechanism",
@@ -264,6 +277,7 @@ __all__ = [
     "ParsedTurn",
     "ParserContext",
     "PolicyConfig",
+    "PricingContext",
     "PricingTable",
     "Process",
     "ProcessClosedError",
@@ -271,9 +285,12 @@ __all__ = [
     "ProcessOutput",
     "Provider",
     "ProviderCapabilityError",
+    "ProviderCatalog",
     "ProviderError",
+    "ProviderPlugin",
     "ProviderProfile",
     "ProviderStatus",
+    "ProviderTestSupport",
     "ProviderUsage",
     "RandomIds",
     "RateLimitStatus",

{agentshim-0.19.0 → agentshim-0.21.0}/agentshim/agent.py

@@ -38,7 +38,7 @@ from agentshim.core.skills import SkillTracker
 from agentshim.core.turn import TurnRequest, TurnResult, coerce_request
 from agentshim.execution.executor import CommandRequest
 from agentshim.execution.host import HostCommandExecutor
-from agentshim.providers import get_provider
+from agentshim.providers import DEFAULT_CATALOG, ProviderCatalog, get_provider
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Mapping, Sequence
@@ -51,14 +51,14 @@ if TYPE_CHECKING:
     from agentshim.execution.executor import CommandExecutor, CommandHandle, CommandResult
 
 
-def _resolve_provider(provider: str | Provider) -> Provider:
+def _resolve_provider(provider: str | Provider, catalog: ProviderCatalog) -> Provider:
     """Resolve a provider name to a provider instance.
 
     This module sits above ``providers`` precisely so the documented
     ``CliAgent("claude")`` spelling can be a plain module-level import.
     """
     if isinstance(provider, str):
-        return get_provider(provider)
+        return get_provider(provider, catalog=catalog)
     return provider
 
 
@@ -82,6 +82,7 @@ class CliAgent:
         event_handlers: Sequence[AgentEventHandler] = (),
         check_timeout: float = 15.0,
         log: Callable[[str], None] | None = None,
+        catalog: ProviderCatalog = DEFAULT_CATALOG,
     ) -> None:
         """Configure a provider CLI and prove it is usable before any turn runs.
 
@@ -104,8 +105,9 @@ class CliAgent:
             check_timeout: Seconds allowed for the one-off health check. It is
                 not a budget for a turn.
             log: Sink for agentshim's own progress lines; dropped by default.
+            catalog: Provider names and implementations to use; defaults to the built-ins.
         """
-        self.provider: Provider = _resolve_provider(provider)
+        self.provider: Provider = _resolve_provider(provider, catalog)
         self.profile: ProviderProfile = self.provider.profile
         self.model = model
         self.executor: CommandExecutor = executor if executor is not None else HostCommandExecutor()

{agentshim-0.19.0 → agentshim-0.21.0}/agentshim/core/__init__.py

@@ -19,6 +19,7 @@ from .auth import (
     FileCredential,
     HostAuthGap,
     HostAuthUnplannableError,
+    LoginSpec,
     SettingsSpec,
     StagedCredentialFile,
     host_auth_plan,
@@ -95,9 +96,10 @@ from .mcp import (
     StdioMcpServer,
     install_config_file,
 )
-from .models import ModelSpec, ModelTable, context_window, default_models, model_spec
+from .models import ModelSpec, ModelTable
 from .permissions import ApprovalPolicy, NativeMode, NativePermissions
-from .pricing import ModelPricing, PricingTable, cost_usd, default_pricing, price_for
+from .plugin import ConnectionOptions, PricingContext, ProviderPlugin, ProviderTestSupport
+from .pricing import ModelPricing, PricingTable, cost_usd
 from .profile import (
     ConfigScope,
     McpMechanism,
@@ -148,6 +150,7 @@ __all__ = [
     "CompositeEventHandler",
     "ConfigFileInstallation",
     "ConfigScope",
+    "ConnectionOptions",
     "ConsoleEventHandler",
     "ContextualStreamParser",
     "Continuity",
@@ -169,6 +172,7 @@ __all__ = [
     "IdAllocator",
     "InMemoryCheckpointStore",
     "Lifecycle",
+    "LoginSpec",
     "McpConfigError",
     "McpInstallation",
     "McpMechanism",
@@ -188,13 +192,16 @@ __all__ = [
     "ParsedTurn",
     "ParserContext",
     "PolicyConfig",
+    "PricingContext",
     "PricingTable",
     "ProcessClosedError",
     "Provider",
     "ProviderCapabilityError",
     "ProviderError",
+    "ProviderPlugin",
     "ProviderProfile",
     "ProviderStatus",
+    "ProviderTestSupport",
     "ProviderUsage",
     "RandomIds",
     "RateLimitStatus",
@@ -245,20 +252,15 @@ __all__ = [
     "UsageReport",
     "compact_json",
     "compose_event_handlers",
-    "context_window",
     "cost_usd",
-    "default_models",
-    "default_pricing",
     "dialect_problems",
     "host_auth_plan",
     "install_config_file",
     "interactive_env",
     "materialize",
-    "model_spec",
     "normalize",
     "normalized_usage",
     "parse_json_object",
     "plan_auth",
     "prepare_config_home",
-    "price_for",
 ]

{agentshim-0.19.0 → agentshim-0.21.0}/agentshim/core/auth.py

@@ -151,6 +151,44 @@ class EndpointSpec:
     credentials: frozenset[CredentialKind] = frozenset({CredentialKind.API_KEY})
 
 
+@dataclass(frozen=True)
+class LoginSpec:
+    """How a person signs a CLI in, as the CLI itself does it.
+
+    ``argv`` follows the binary and starts the CLI's own subscription login
+    (a browser page, or a URL to open). ``device_argv`` is the variant for a
+    machine without a usable browser, where the CLI prints a code to enter on
+    another device, or ``None`` when the CLI has none. ``needs_terminal`` is
+    true when the command prompts the person (a menu, a pasted code), so it
+    must run attached to a terminal; false when it runs unattended and only
+    prints a URL. Whether a CLI is signed in is not here: the provider's
+    ``ProbeSpec.auth`` reads that, where the CLI has a status command.
+    """
+
+    argv: tuple[str, ...]
+    device_argv: tuple[str, ...] | None = None
+    needs_terminal: bool = False
+
+    def __post_init__(self) -> None:
+        """Reject an empty command."""
+        if not self.argv or (self.device_argv is not None and not self.device_argv):
+            msg = "LoginSpec commands need at least one argument"
+            raise ValueError(msg)
+
+    def command(self, binary: str, *, device: bool = False) -> tuple[str, ...]:
+        """The full command line, with *binary* first.
+
+        Raises:
+            ValueError: *device* is asked for and the CLI has no device login.
+        """
+        if not device:
+            return (binary, *self.argv)
+        if self.device_argv is None:
+            msg = f"{binary} has no device login"
+            raise ValueError(msg)
+        return (binary, *self.device_argv)
+
+
 @dataclass(frozen=True)
 class AuthPolicy:
     """Which credentials a caller allows, and the endpoint to use.

agentshim-0.21.0/agentshim/core/models.py

@@ -0,0 +1,209 @@
+"""Provider-independent model facts and tables."""
+
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass, field, replace
+from typing import TYPE_CHECKING, cast
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+
+@dataclass(frozen=True)
+class ModelSpec:
+    """One model's context window, with where and when it was read.
+
+    Attributes:
+        vendor: Who serves the model (``"openai"``, ``"anthropic"``).
+        model: The model id as the vendor names it.
+        context_window: The model's context window in tokens (input and
+            output together), at the vendor's default for that id.
+        source: URL of the official page the number was read from.
+        checked: Date the number was last checked against ``source``.
+        display_name: A readable name for the model (``"Opus 5.5"``), or
+            ``None`` for a caller-built entry that has none.
+        family: The model line the model belongs to (``"Claude"``, ``"GPT"``,
+            ``"Gemini"``); set together with ``display_name``.
+        tier: The model's rank within its family, ``1`` the smallest and
+            cheapest; versions of one tier share a rank. ``None`` for a model
+            that sits on no tier ladder.
+        tier_name: The tier's readable name (``"Opus"``); set together with
+            ``tier``.
+        generation_id: A short stable token naming the model's generation
+            within its vendor (``"5.5"``); every model of one generation
+            shares it, and no two generations of a vendor do.
+        generation: The generation as people call it (``"Claude 5.5"``,
+            ``"GPT-6"``); set together with ``generation_id``.
+        generation_rank: The generation's rank among its vendor's, ``1`` the
+            newest; set together with ``generation_id``. ``ModelTable``
+            checks that one vendor's generations have distinct ranks.
+    """
+
+    vendor: str
+    model: str
+    context_window: int
+    source: str
+    checked: dt.date
+    display_name: str | None = None
+    family: str | None = None
+    tier: int | None = None
+    tier_name: str | None = None
+    generation_id: str | None = None
+    generation: str | None = None
+    generation_rank: int | None = None
+
+    def __post_init__(self) -> None:
+        """Reject a missing name, source or date, and a window that is not a positive int."""
+        for name in ("vendor", "model"):
+            value: object = getattr(self, name)
+            if not isinstance(value, str) or not value.strip():
+                msg = f"{name} must be a non-empty string"
+                raise ValueError(msg)
+        source = cast("object", self.source)
+        if not isinstance(source, str) or not source.startswith("https://"):
+            msg = f"{self.vendor}/{self.model}: source must be an https:// URL"
+            raise ValueError(msg)
+        checked = cast("object", self.checked)
+        if not isinstance(checked, dt.date) or isinstance(checked, dt.datetime):
+            msg = f"{self.vendor}/{self.model}: checked must be a datetime.date"
+            raise TypeError(msg)
+        window = cast("object", self.context_window)
+        if isinstance(window, bool) or not isinstance(window, int) or window <= 0:
+            msg = f"{self.vendor}/{self.model}: context_window must be a positive int"
+            raise ValueError(msg)
+        self._check_presentation()
+        self._check_generation()
+
+    def _check_generation(self) -> None:
+        """Reject a half-set generation triple, a blank name, and a rank that is not a positive int."""
+        parts = (self.generation_id, self.generation, self.generation_rank)
+        if any(part is None for part in parts) and any(part is not None for part in parts):
+            msg = (
+                f"{self.vendor}/{self.model}: "
+                "generation_id, generation and generation_rank are set together"
+            )
+            raise ValueError(msg)
+        for name in ("generation_id", "generation"):
+            value: object = getattr(self, name)
+            if value is not None and (not isinstance(value, str) or not value.strip()):
+                msg = f"{self.vendor}/{self.model}: {name} must be a non-empty string"
+                raise ValueError(msg)
+        rank = cast("object", self.generation_rank)
+        if rank is not None and (isinstance(rank, bool) or not isinstance(rank, int) or rank < 1):
+            msg = f"{self.vendor}/{self.model}: generation_rank must be a positive int"
+            raise ValueError(msg)
+
+    def _check_presentation(self) -> None:
+        """Reject a half-set name pair or tier pair, and a tier that is not a positive int."""
+        for first, second in (("display_name", "family"), ("tier", "tier_name")):
+            if (getattr(self, first) is None) != (getattr(self, second) is None):
+                msg = f"{self.vendor}/{self.model}: {first} and {second} are set together"
+                raise ValueError(msg)
+        for name in ("display_name", "family", "tier_name"):
+            value: object = getattr(self, name)
+            if value is not None and (not isinstance(value, str) or not value.strip()):
+                msg = f"{self.vendor}/{self.model}: {name} must be a non-empty string"
+                raise ValueError(msg)
+        tier = cast("object", self.tier)
+        if tier is not None and (isinstance(tier, bool) or not isinstance(tier, int) or tier < 1):
+            msg = f"{self.vendor}/{self.model}: tier must be a positive int"
+            raise ValueError(msg)
+        if self.tier is not None and self.family is None:
+            msg = f"{self.vendor}/{self.model}: tier needs a family"
+            raise ValueError(msg)
+
+    @property
+    def key(self) -> tuple[str, str]:
+        """The ``(vendor, model)`` this entry describes."""
+        return (self.vendor, self.model)
+
+
+@dataclass(frozen=True)
+class ModelTable:
+    """A versioned set of :class:`ModelSpec` entries.
+
+    Attributes:
+        version: Names this set of facts; change it whenever a fact changes.
+        last_updated: Date the table as a whole was last updated. No entry
+            may have been checked later.
+        entries: One entry per ``(vendor, model)``.
+    """
+
+    version: str
+    last_updated: dt.date
+    entries: tuple[ModelSpec, ...] = field(default=())
+
+    def __post_init__(self) -> None:
+        """Reject a missing version, duplicate keys, and entries checked after ``last_updated``."""
+        version = cast("object", self.version)
+        if not isinstance(version, str) or not version.strip():
+            msg = "version must be a non-empty string"
+            raise ValueError(msg)
+        object.__setattr__(self, "entries", tuple(self.entries))
+        seen: set[tuple[str, str]] = set()
+        for entry in self.entries:
+            if not isinstance(cast("object", entry), ModelSpec):
+                msg = f"entries must be ModelSpec, got {entry!r}"
+                raise TypeError(msg)
+            if entry.key in seen:
+                msg = f"duplicate model entry for {entry.vendor}/{entry.model}"
+                raise ValueError(msg)
+            seen.add(entry.key)
+            if entry.checked > self.last_updated:
+                msg = (
+                    f"{entry.vendor}/{entry.model} was checked {entry.checked}, "
+                    f"after the table's last_updated {self.last_updated}"
+                )
+                raise ValueError(msg)
+        self._check_generations()
+
+    def _check_generations(self) -> None:
+        """Reject a vendor whose generations disagree on a name or rank, or share a rank."""
+        by_id: dict[tuple[str, str], tuple[str | None, int | None]] = {}
+        by_rank: dict[tuple[str, int], str] = {}
+        for entry in self.entries:
+            if entry.generation_id is None or entry.generation_rank is None:
+                continue
+            known = by_id.setdefault(
+                (entry.vendor, entry.generation_id), (entry.generation, entry.generation_rank)
+            )
+            if known != (entry.generation, entry.generation_rank):
+                msg = (
+                    f"{entry.vendor}/{entry.model}: generation {entry.generation_id!r} "
+                    "has another name or rank on another model"
+                )
+                raise ValueError(msg)
+            holder = by_rank.setdefault((entry.vendor, entry.generation_rank), entry.generation_id)
+            if holder != entry.generation_id:
+                msg = (
+                    f"{entry.vendor}: generations {holder!r} and {entry.generation_id!r} "
+                    f"share rank {entry.generation_rank}"
+                )
+                raise ValueError(msg)
+
+    def get(self, vendor: str, model: str) -> ModelSpec | None:
+        """The entry for exactly ``(vendor, model)``, or ``None``."""
+        for entry in self.entries:
+            if entry.key == (vendor, model):
+                return entry
+        return None
+
+    def with_entries(
+        self,
+        entries: Iterable[ModelSpec],
+        *,
+        version: str,
+        last_updated: dt.date | None = None,
+    ) -> ModelTable:
+        """A new table with *entries* added, replacing any with the same key."""
+        added = tuple(entries)
+        by_key = {entry.key: entry for entry in self.entries}
+        by_key.update({entry.key: entry for entry in added})
+        latest = max([self.last_updated, *(entry.checked for entry in added)])
+        return replace(
+            self,
+            version=version,
+            last_updated=last_updated or latest,
+            entries=tuple(by_key.values()),
+        )