agentshim 0.20.0__tar.gz → 0.21.0__tar.gz

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

@@ -1,5 +1,22 @@
 # 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

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

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

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

@@ -51,6 +51,7 @@ from .core import (
     IdAllocator,
     InMemoryCheckpointStore,
     Lifecycle,
+    LoginSpec,
     McpConfigError,
     McpInstallation,
     McpMechanism,
@@ -184,7 +185,7 @@ from .providers.opencode import OpencodeProvider
 from .runtime import Agent
 from .session import Session, Turn, TurnTicket, map_mcp_servers
 
-__version__ = "0.20.0"
+__version__ = "0.21.0"
 
 __all__ = [  # noqa: RUF022 - public API test uses Python's case-sensitive order
     "Agent",
@@ -253,6 +254,7 @@ __all__ = [  # noqa: RUF022 - public API test uses Python's case-sensitive order
     "IdAllocator",
     "InMemoryCheckpointStore",
     "Lifecycle",
+    "LoginSpec",
     "McpConfigError",
     "McpInstallation",
     "McpMechanism",

{agentshim-0.20.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,
@@ -171,6 +172,7 @@ __all__ = [
     "IdAllocator",
     "InMemoryCheckpointStore",
     "Lifecycle",
+    "LoginSpec",
     "McpConfigError",
     "McpInstallation",
     "McpMechanism",

{agentshim-0.20.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.20.0 → agentshim-0.21.0}/agentshim/core/models.py

@@ -30,6 +30,14 @@ class ModelSpec:
             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
@@ -41,6 +49,9 @@ class ModelSpec:
     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."""
@@ -62,6 +73,26 @@ class ModelSpec:
             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."""
@@ -125,6 +156,31 @@ class ModelTable:
                     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``."""

{agentshim-0.20.0 → agentshim-0.21.0}/agentshim/core/profile.py

@@ -16,7 +16,7 @@ from .permissions import NativeMode
 if TYPE_CHECKING:
     from collections.abc import Mapping
 
-    from .auth import CredentialSource, EndpointSpec, SettingsSpec
+    from .auth import CredentialSource, EndpointSpec, LoginSpec, SettingsSpec
 
 
 class McpMechanism(Enum):
@@ -242,6 +242,10 @@ class ProviderProfile:
     #: agentshim knows of none: a caller may still pass any model, at its own
     #: risk. A model's facts (its context window) are in ``model_spec``.
     models: tuple[str, ...] = ()
+    #: The CLI's own command for a person to sign in (0.21.0+), or ``None``
+    #: when it has none (Gemini CLI signs in on its first interactive run).
+    #: Signed-in state is read by the provider's ``ProbeSpec``.
+    login: LoginSpec | None = None
 
     @property
     def default_model(self) -> str | None:

{agentshim-0.20.0 → agentshim-0.21.0}/agentshim/models.py

@@ -88,4 +88,4 @@ def default_models(*, catalog: ProviderCatalog | None = None) -> ModelTable:
             by_key[entry.key] = entry
     entries = tuple(by_key.values())
     updated = max((entry.checked for entry in entries), default=dt.date(2026, 10, 17))
-    return ModelTable(version="2026-10-17.1", last_updated=updated, entries=entries)
+    return ModelTable(version="2026-10-18.1", last_updated=updated, entries=entries)

{agentshim-0.20.0 → agentshim-0.21.0}/agentshim/providers/claude/model_data.py

@@ -16,6 +16,7 @@ _PRICE_CHECKED = dt.date(2026, 9, 27)
 def _anthropic_model(
     model: str, context_window: int, tier: tuple[int, str], version: str
 ) -> ModelSpec:
+    generation_id, generation_rank = _GENERATIONS[version]
     return ModelSpec(
         vendor="anthropic",
         model=model,
@@ -26,9 +27,18 @@ def _anthropic_model(
         family="Claude",
         tier=tier[0],
         tier_name=tier[1],
+        generation_id=generation_id,
+        generation=f"Claude {version}",
+        generation_rank=generation_rank,
     )
 
 
+#: Claude's generations by version, newest first: ``(generation_id, rank)``.
+_GENERATIONS = {
+    version: (version, rank)
+    for rank, version in enumerate(("5.5", "5.1", "5", "4.8", "4.7", "4.6", "4.5"), start=1)
+}
+
 _HAIKU = (1, "Haiku")
 _SONNET = (2, "Sonnet")
 _OPUS = (3, "Opus")

{agentshim-0.20.0 → agentshim-0.21.0}/agentshim/providers/claude/provider.py

@@ -11,6 +11,7 @@ from agentshim.core.auth import (
     EnvCredential,
     ExternalCredential,
     FileCredential,
+    LoginSpec,
     SettingsSpec,
 )
 from agentshim.core.errors import FailureKind, ProviderCapabilityError, SessionResumeError
@@ -83,6 +84,9 @@ PROFILE = ProviderProfile(
         "claude-haiku-4-5",
     ),
     display_name="Claude Code",
+    # ``claude auth login`` opens a browser page and, when none opens, asks for a
+    # pasted code, so it needs a terminal. It has no device-code variant.
+    login=LoginSpec(argv=("auth", "login"), needs_terminal=True),
     binary="claude",
     supports_resume=True,
     supports_reasoning_effort=True,

{agentshim-0.20.0 → agentshim-0.21.0}/agentshim/providers/codex/model_data.py

@@ -15,8 +15,10 @@ def _openai_model(
     model: str,
     context_window: int,
     display_name: str,
+    version: str,
     tier: tuple[int, str] | None = None,
 ) -> ModelSpec:
+    generation_id, generation_rank = _GENERATIONS[version]
     return ModelSpec(
         vendor="openai",
         model=model,
@@ -27,9 +29,17 @@ def _openai_model(
         family="GPT",
         tier=None if tier is None else tier[0],
         tier_name=None if tier is None else tier[1],
+        generation_id=generation_id,
+        generation=f"GPT-{version}",
+        generation_rank=generation_rank,
     )
 
 
+#: GPT's generations by version, newest first: ``(generation_id, rank)``.
+_GENERATIONS = {
+    version: (version, rank) for rank, version in enumerate(("6.1", "6", "5.6", "5.5"), start=1)
+}
+
 _LUNA = (1, "Luna")
 _TERRA = (2, "Terra")
 _SOL = (3, "Sol")
@@ -37,14 +47,14 @@ _ASTRA = (4, "Astra")
 _OPENAI_1_05M = 1_050_000
 
 MODEL_ENTRIES = (
-    _openai_model("gpt-6-astra", _OPENAI_1_05M, "GPT-6 Astra", _ASTRA),
-    _openai_model("gpt-6.1-sol", _OPENAI_1_05M, "GPT-6.1 Sol", _SOL),
-    _openai_model("gpt-6-sol", _OPENAI_1_05M, "GPT-6 Sol", _SOL),
-    _openai_model("gpt-6-luna", _OPENAI_1_05M, "GPT-6 Luna", _LUNA),
-    _openai_model("gpt-5.6-sol", _OPENAI_1_05M, "GPT-5.6 Sol", _SOL),
-    _openai_model("gpt-5.6-terra", _OPENAI_1_05M, "GPT-5.6 Terra", _TERRA),
-    _openai_model("gpt-5.6-luna", _OPENAI_1_05M, "GPT-5.6 Luna", _LUNA),
-    _openai_model("gpt-5.5", _OPENAI_1_05M, "GPT-5.5"),
+    _openai_model("gpt-6-astra", _OPENAI_1_05M, "GPT-6 Astra", "6", _ASTRA),
+    _openai_model("gpt-6.1-sol", _OPENAI_1_05M, "GPT-6.1 Sol", "6.1", _SOL),
+    _openai_model("gpt-6-sol", _OPENAI_1_05M, "GPT-6 Sol", "6", _SOL),
+    _openai_model("gpt-6-luna", _OPENAI_1_05M, "GPT-6 Luna", "6", _LUNA),
+    _openai_model("gpt-5.6-sol", _OPENAI_1_05M, "GPT-5.6 Sol", "5.6", _SOL),
+    _openai_model("gpt-5.6-terra", _OPENAI_1_05M, "GPT-5.6 Terra", "5.6", _TERRA),
+    _openai_model("gpt-5.6-luna", _OPENAI_1_05M, "GPT-5.6 Luna", "5.6", _LUNA),
+    _openai_model("gpt-5.5", _OPENAI_1_05M, "GPT-5.5", "5.5"),
 )
 
 _OPENAI_NOTE = (

{agentshim-0.20.0 → agentshim-0.21.0}/agentshim/providers/codex/provider.py

@@ -11,6 +11,7 @@ from agentshim.core.auth import (
     EndpointSpec,
     EnvCredential,
     FileCredential,
+    LoginSpec,
     classify_json_field,
 )
 from agentshim.core.errors import ProviderCapabilityError, SessionResumeError
@@ -87,6 +88,9 @@ PROFILE = ProviderProfile(
     ),
     display_name="Codex",
     binary="codex",
+    # ``codex login`` prints a URL and waits for the browser redirect on a local
+    # port; ``--device-auth`` prints a code to enter on another device instead.
+    login=LoginSpec(argv=("login",), device_argv=("login", "--device-auth")),
     supports_resume=True,
     supports_reasoning_effort=True,
     mcp=McpMechanism.CLI_FLAGS,

{agentshim-0.20.0 → agentshim-0.21.0}/agentshim/providers/copilot/provider.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import json
 from typing import TYPE_CHECKING, Any
 
-from agentshim.core.auth import CredentialKind, EnvCredential, FileCredential
+from agentshim.core.auth import CredentialKind, EnvCredential, FileCredential, LoginSpec
 from agentshim.core.errors import ProviderCapabilityError
 from agentshim.core.mcp import FlagsInstallation, HttpMcpServer, NoopInstallation
 from agentshim.core.profile import McpMechanism, OutputSchemaStyle, ProviderProfile
@@ -28,6 +28,8 @@ PROFILE = ProviderProfile(
     name="copilot",
     display_name="Copilot CLI",
     binary="copilot",
+    # ``copilot login`` runs GitHub's device flow: a code to enter at a URL.
+    login=LoginSpec(argv=("login",)),
     supports_resume=True,
     # ``--effort`` exists on the CLI but the provider does not expose it: the
     # levels are model-specific and unvalidated, so a request naming one is

{agentshim-0.20.0 → agentshim-0.21.0}/agentshim/providers/opencode/model_data.py

@@ -19,6 +19,9 @@ def _google(model: str, context_window: int, display_name: str, tier: tuple[int,
         family="Gemini",
         tier=tier[0],
         tier_name=tier[1],
+        generation_id="3",
+        generation="Gemini 3",
+        generation_rank=1,
     )
 
 

{agentshim-0.20.0 → agentshim-0.21.0}/agentshim/providers/opencode/provider.py

@@ -17,6 +17,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
 
+from agentshim.core.auth import LoginSpec
 from agentshim.core.errors import ProviderCapabilityError, SessionResumeError
 from agentshim.core.mcp import (
     HttpMcpServer,
@@ -52,6 +53,8 @@ PROFILE = ProviderProfile(
     models=("google-vertex/gemini-3-pro-preview",),
     display_name="opencode",
     binary="opencode",
+    # ``opencode auth login`` prompts for a provider and its credential.
+    login=LoginSpec(argv=("auth", "login"), needs_terminal=True),
     supports_resume=True,
     # ``run --session <id>`` continues a stored session.
     supports_reasoning_effort=False,

{agentshim-0.20.0 → agentshim-0.21.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentshim"
-version = "0.20.0"
+version = "0.21.0"
 description = "Provider-agnostic coding-agent CLI shims"
 readme = "README.md"
 license = "MIT"