agentshim 0.16.0__tar.gz → 0.18.0__tar.gz

{agentshim-0.16.0 → agentshim-0.18.0}/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.18.0 (2026-10-16)
+
+### Added
+
+- `context_window(provider, model)` and `model_spec(provider, model)`: a model's context
+  window in tokens from a static, versioned table (`ModelSpec`, `ModelTable`,
+  `default_models()`), each entry citing the vendor page it was read from. Covers the
+  Claude 5 family (`claude-fable-5-1`, `claude-opus-5-5`, `claude-sonnet-5-5`,
+  `claude-haiku-5-5`, all 1M) and current OpenAI models. An unknown model, or a
+  bracketed variant, returns `None`; the lookup never matches by prefix.
+- `ProviderProfile.models`: the model ids a provider's CLI is known to run, the default
+  first, and `ProviderProfile.default_model`. Claude, Codex and opencode declare theirs.
+
+## 0.17.0 (2026-10-15)
+
+### Added
+
+- `host_auth_plan(profile, env=, home=)` returns the `AuthPlan` that reproduces how the
+  CLI logs in by itself on a host: the first present credential source of any kind, plus
+  the host's endpoint variables exactly as set, so a confined copy given only the plan
+  sends the same credential to the same place. A host base URL is reproduced, not
+  validated, and a credential goes to the host's endpoint whatever its kind (Claude Code
+  sends `CLAUDE_CODE_OAUTH_TOKEN` to a custom `ANTHROPIC_BASE_URL`). It raises
+  `HostAuthUnplannableError`, whose `reason` (`HostAuthGap`) is `UNCLASSIFIED`,
+  `NO_CREDENTIAL`, `EXTERNAL_CREDENTIAL` or `SETTINGS_ENV`, when no plan can reproduce
+  the host's login.
+- `ExternalCredential`, a `CredentialSource` for a way the CLI logs in that no plan can
+  hand over, detected by variables, paths or settings keys. Claude declares a cloud
+  provider (`CLAUDE_CODE_USE_BEDROCK`, `_VERTEX`, `_FOUNDRY`), `apiKeyHelper`, and
+  Anthropic profiles at their documented places in its precedence; Gemini declares an
+  auth type selected in settings or by variable, and `.gemini/.env`.
+- `ProviderProfile.settings` (`SettingsSpec`): the settings files a CLI reads at start
+  that can change how it logs in, and the key of the block it applies over its
+  environment (Claude's `env`).
+
+### Changed
+
+- `CredentialSource` is now `EnvCredential | FileCredential | ExternalCredential`;
+  code that matched on two variants must handle the third. `plan_auth` never chooses an
+  `ExternalCredential` and names a present one in `AuthPlan.withheld`.
+
 ## 0.16.0 (2026-10-14)
 
 ### Added

{agentshim-0.16.0 → agentshim-0.18.0}/PKG-INFO

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

{agentshim-0.16.0 → agentshim-0.18.0}/agentshim/__init__.py

@@ -40,9 +40,12 @@ from .core import (
     EndpointSpec,
     EnvCredential,
     EventHandlerBase,
+    ExternalCredential,
     FailureKind,
     FileCredential,
     FlagsInstallation,
+    HostAuthGap,
+    HostAuthUnplannableError,
     HttpMcpServer,
     IdAllocator,
     InMemoryCheckpointStore,
@@ -54,6 +57,8 @@ from .core import (
     McpServer,
     McpTransport,
     ModelPricing,
+    ModelSpec,
+    ModelTable,
     NativeMode,
     NativePermissions,
     NoopInstallation,
@@ -88,6 +93,7 @@ from .core import (
     SessionStarted,
     SessionState,
     SessionStateError,
+    SettingsSpec,
     SkillInvoked,
     SkillScope,
     SkillsDiscovered,
@@ -120,12 +126,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,
@@ -166,7 +176,7 @@ from .providers.opencode import OpencodeProvider
 from .runtime import Agent
 from .session import Session, Turn, TurnTicket, map_mcp_servers
 
-__version__ = "0.16.0"
+__version__ = "0.18.0"
 
 __all__ = [
     "Agent",
@@ -219,10 +229,13 @@ __all__ = [
     "EndpointSpec",
     "EnvCredential",
     "EventHandlerBase",
+    "ExternalCredential",
     "FailureKind",
     "FileCredential",
     "FlagsInstallation",
     "GeminiProvider",
+    "HostAuthGap",
+    "HostAuthUnplannableError",
     "HostCommandExecutor",
     "HostProcess",
     "HttpMcpServer",
@@ -236,6 +249,8 @@ __all__ = [
     "McpServer",
     "McpTransport",
     "ModelPricing",
+    "ModelSpec",
+    "ModelTable",
     "NativeMode",
     "NativePermissions",
     "NoRunningTurnError",
@@ -278,6 +293,7 @@ __all__ = [
     "SessionStarted",
     "SessionState",
     "SessionStateError",
+    "SettingsSpec",
     "SkillInvoked",
     "SkillScope",
     "SkillSignal",
@@ -318,14 +334,18 @@ __all__ = [
     "compact_json",
     "compose_event_handlers",
     "confine",
+    "context_window",
     "cost_usd",
+    "default_models",
     "default_pricing",
     "dialect_problems",
     "get_provider",
+    "host_auth_plan",
     "install_config_file",
     "interactive_env",
     "map_mcp_servers",
     "materialize",
+    "model_spec",
     "normalize",
     "normalized_usage",
     "parse_json_object",

{agentshim-0.16.0 → agentshim-0.18.0}/agentshim/core/__init__.py

@@ -15,8 +15,13 @@ from .auth import (
     CredentialSource,
     EndpointSpec,
     EnvCredential,
+    ExternalCredential,
     FileCredential,
+    HostAuthGap,
+    HostAuthUnplannableError,
+    SettingsSpec,
     StagedCredentialFile,
+    host_auth_plan,
     plan_auth,
 )
 from .checkpoints import Checkpoint, CheckpointStore, InMemoryCheckpointStore
@@ -90,6 +95,7 @@ from .mcp import (
     StdioMcpServer,
     install_config_file,
 )
+from .models import ModelSpec, ModelTable, context_window, default_models, model_spec
 from .permissions import ApprovalPolicy, NativeMode, NativePermissions
 from .pricing import ModelPricing, PricingTable, cost_usd, default_pricing, price_for
 from .profile import (
@@ -153,9 +159,12 @@ __all__ = [
     "EndpointSpec",
     "EnvCredential",
     "EventHandlerBase",
+    "ExternalCredential",
     "FailureKind",
     "FileCredential",
     "FlagsInstallation",
+    "HostAuthGap",
+    "HostAuthUnplannableError",
     "HttpMcpServer",
     "IdAllocator",
     "InMemoryCheckpointStore",
@@ -167,6 +176,8 @@ __all__ = [
     "McpServer",
     "McpTransport",
     "ModelPricing",
+    "ModelSpec",
+    "ModelTable",
     "NativeMode",
     "NativePermissions",
     "NoRunningTurnError",
@@ -201,6 +212,7 @@ __all__ = [
     "SessionStarted",
     "SessionState",
     "SessionStateError",
+    "SettingsSpec",
     "SkillInvoked",
     "SkillScope",
     "SkillSignal",
@@ -233,12 +245,16 @@ __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",

{agentshim-0.16.0 → agentshim-0.18.0}/agentshim/core/auth.py

@@ -16,6 +16,12 @@ exact environment variables and files to deliver. The caller delivers the
 plan and nothing more of the provider's ``auth_env_vars`` or ``auth_files``;
 the readiness probe then reports which kind of credential the CLI says it is
 using (``ProviderStatus.credential``), so the caller can confirm it.
+
+A caller with no policy of its own, that wants a confined copy of the CLI to
+log in exactly as the CLI would on the host, asks ``host_auth_plan`` instead:
+it applies the CLI's own precedence with every kind allowed and the host's
+endpoint as it is, and refuses (``HostAuthUnplannableError``) when the host
+CLI would log in some way a plan cannot reproduce.
 """
 
 from __future__ import annotations
@@ -85,7 +91,49 @@ class FileCredential:
         return self.classify(contents)
 
 
-CredentialSource = EnvCredential | FileCredential
+@dataclass(frozen=True)
+class ExternalCredential:
+    """A way the CLI logs in that no plan can hand to another copy of it.
+
+    A cloud provider selected by a variable (whose own credentials live in
+    other tools' state), a helper command named in a settings file, a
+    credential store outside the CLI's state root. It is declared at its place
+    in the precedence order so ``host_auth_plan`` knows when the host CLI would
+    use it; ``plan_auth`` never chooses it. It is present when any variable in
+    ``env`` is set, any home-relative path in ``paths`` exists, or any of the
+    profile's ``settings`` files has one of ``settings_keys`` at its top level.
+    """
+
+    label: str
+    env: tuple[str, ...] = ()
+    paths: tuple[str, ...] = ()
+    settings_keys: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        """Require some way to detect the credential."""
+        if not (self.env or self.paths or self.settings_keys):
+            msg = f"ExternalCredential {self.label!r} needs an env, paths or settings_keys entry"
+            raise ValueError(msg)
+
+
+CredentialSource = EnvCredential | FileCredential | ExternalCredential
+#: The sources a plan can hand over.
+_DeliverableSource = EnvCredential | FileCredential
+
+
+@dataclass(frozen=True)
+class SettingsSpec:
+    """The JSON settings files a CLI reads from its home when it starts.
+
+    ``files`` are home-relative paths. ``env_key`` names a top-level object
+    whose string entries the CLI applies over its own environment (Claude
+    Code's ``env``), or ``None`` when the CLI has no such block. Settings can
+    change which credential or endpoint the CLI uses, so ``host_auth_plan``
+    reads them; neither plan function delivers them.
+    """
+
+    files: tuple[str, ...]
+    env_key: str | None = None
 
 
 @dataclass(frozen=True)
@@ -170,6 +218,37 @@ class AuthUnavailableError(AgentShimError):
     """
 
 
+class HostAuthGap(str, Enum):
+    """Why ``host_auth_plan`` cannot reproduce how the host CLI logs in.
+
+    ``UNCLASSIFIED``: the profile declares no credential sources. ``NO_CREDENTIAL``:
+    none of the declared sources is present, so the CLI either cannot log in
+    or does it some way agentshim does not know. ``EXTERNAL_CREDENTIAL``: the
+    CLI would use an ``ExternalCredential``. ``SETTINGS_ENV``: a settings file
+    sets a credential or endpoint variable of its own, so the environment the
+    CLI logs in with is not the caller's.
+    """
+
+    UNCLASSIFIED = "unclassified"
+    NO_CREDENTIAL = "no_credential"
+    EXTERNAL_CREDENTIAL = "external_credential"
+    SETTINGS_ENV = "settings_env"
+
+
+class HostAuthUnplannableError(AgentShimError):
+    """The host CLI's login cannot be reproduced by a plan; ``reason`` says why.
+
+    The message names the variables or files involved, never a value. A caller
+    that still wants the CLI logged in elsewhere has only the host's whole auth
+    state (``auth_env_vars`` and ``auth_files``) to hand over.
+    """
+
+    def __init__(self, reason: HostAuthGap, message: str) -> None:
+        """Record *reason* beside the message."""
+        super().__init__(message)
+        self.reason = reason
+
+
 def plan_auth(
     profile: ProviderProfile,
     policy: AuthPolicy,
@@ -205,10 +284,6 @@ def plan_auth(
             {name: env[name] for name in profile.endpoint.companion_env if _set(env, name)}
         )
 
-    delivered = set(delivered_env) | {staged.home_path for staged in files}
-    on_host = {name for name in _host_auth_names(profile) if _set(env, name)}
-    on_host |= {path for path in profile.auth_files if (home / path).is_file()}
-    on_host |= set(present)
     return AuthPlan(
         provider=profile.name,
         credential=kind,
@@ -216,7 +291,61 @@ def plan_auth(
         endpoint=policy.endpoint,
         env=MappingProxyType(delivered_env),
         files=files,
-        withheld=tuple(sorted(on_host - delivered)),
+        withheld=_withheld(profile, env, home, present, _delivered(delivered_env, files)),
+    )
+
+
+def host_auth_plan(profile: ProviderProfile, *, env: Mapping[str, str], home: Path) -> AuthPlan:
+    """Say how *profile*'s CLI logs in by itself on a host, as a plan a confined copy can use.
+
+    The CLI's own choice: the first present source in ``credential_sources``,
+    of any kind, at whatever endpoint *env* points it to. The plan delivers
+    that credential, and the host's endpoint variables (``EndpointSpec``
+    ``base_url_env`` and ``companion_env``) exactly as they are set, so a
+    confined copy given only the plan sends the same credential to the same
+    place. ``AuthPlan.endpoint`` is the host's base URL, or ``None`` for the
+    vendor's endpoint.
+
+    The host's base URL is reproduced, not validated: a value the CLI cannot
+    use fails the copy the same way it fails the host CLI (Claude Code fails
+    every request with "Invalid URL" and never falls back to its vendor). The
+    credential's kind is not checked against ``EndpointSpec.credentials``
+    either: what the CLI does with a credential and a custom endpoint is the
+    CLI's behaviour, and the copy reproduces it.
+
+    Raises:
+        HostAuthUnplannableError: the profile declares no credential sources,
+            none is present, the CLI would log in with an
+            ``ExternalCredential``, or a settings file sets a credential or
+            endpoint variable; ``reason`` is the matching ``HostAuthGap``.
+    """
+    if not profile.credential_sources:
+        msg = f"{profile.name} declares no credential sources agentshim can classify"
+        raise HostAuthUnplannableError(HostAuthGap.UNCLASSIFIED, msg)
+    settings = _read_settings(profile, home)
+    _refuse_settings_env(profile, settings)
+    chosen, kind = _host_choice(profile, env, home, settings)
+    delivered_env: dict[str, str] = {}
+    files: tuple[StagedCredentialFile, ...] = ()
+    if isinstance(chosen, EnvCredential):
+        delivered_env[chosen.name] = env[chosen.name]
+    else:
+        refreshable = kind is CredentialKind.SUBSCRIPTION
+        files = (StagedCredentialFile(home / chosen.path, chosen.path, refreshable),)
+    endpoint: str | None = None
+    if profile.endpoint is not None:
+        names = (profile.endpoint.base_url_env, *profile.endpoint.companion_env)
+        delivered_env.update({name: env[name] for name in names if _set(env, name)})
+        endpoint = delivered_env.get(profile.endpoint.base_url_env)
+    present = _present_names(profile, env, home, settings)
+    return AuthPlan(
+        provider=profile.name,
+        credential=kind,
+        source=_name(chosen),
+        endpoint=endpoint,
+        env=MappingProxyType(delivered_env),
+        files=files,
+        withheld=_withheld(profile, env, home, present, _delivered(delivered_env, files)),
     )
 
 
@@ -270,11 +399,14 @@ def _choose(
     allowed: frozenset[CredentialKind],
     env: Mapping[str, str],
     home: Path,
-) -> tuple[CredentialSource, CredentialKind, list[str]]:
+) -> tuple[_DeliverableSource, CredentialKind, list[str]]:
     """The first present allowed source, its kind, and every present source's name."""
-    chosen: tuple[CredentialSource, CredentialKind] | None = None
+    chosen: tuple[_DeliverableSource, CredentialKind] | None = None
     present: list[str] = []
     for source in profile.credential_sources:
+        if isinstance(source, ExternalCredential):
+            present += _external_found(profile, source, env, home)
+            continue
         kind = _present_kind(source, env, home)
         if kind is None:
             continue
@@ -286,8 +418,134 @@ def _choose(
     return chosen[0], chosen[1], present
 
 
+def _host_choice(
+    profile: ProviderProfile,
+    env: Mapping[str, str],
+    home: Path,
+    settings: Mapping[str, dict[str, Any]],
+) -> tuple[_DeliverableSource, CredentialKind]:
+    """The source the CLI itself would log in with: the first present one, of any kind."""
+    for source in profile.credential_sources:
+        if isinstance(source, ExternalCredential):
+            found = _external_found(profile, source, env, home, settings)
+            if found:
+                msg = (
+                    f"{profile.name} would log in with {source.label} "
+                    f"({', '.join(found)}), which no plan can hand to another copy of it"
+                )
+                raise HostAuthUnplannableError(HostAuthGap.EXTERNAL_CREDENTIAL, msg)
+            continue
+        kind = _present_kind(source, env, home)
+        if kind is not None:
+            return source, kind
+    wanted = ", ".join(
+        _name(source)
+        for source in profile.credential_sources
+        if not isinstance(source, ExternalCredential)
+    )
+    msg = f"no credential {profile.name} logs in with is present: none of {wanted}"
+    raise HostAuthUnplannableError(HostAuthGap.NO_CREDENTIAL, msg)
+
+
+def _read_settings(profile: ProviderProfile, home: Path) -> dict[str, dict[str, Any]]:
+    """Each of *profile*'s settings files that holds a JSON object, by path."""
+    out: dict[str, dict[str, Any]] = {}
+    for path in profile.settings.files if profile.settings is not None else ():
+        try:
+            data: Any = json.loads((home / path).read_bytes())
+        except (OSError, ValueError):
+            continue
+        if isinstance(data, dict):
+            out[path] = cast("dict[str, Any]", data)
+    return out
+
+
+def _refuse_settings_env(profile: ProviderProfile, settings: Mapping[str, dict[str, Any]]) -> None:
+    """Raise when a settings file's env block sets a variable the CLI logs in with."""
+    key = profile.settings.env_key if profile.settings is not None else None
+    if key is None:
+        return
+    names = _host_auth_names(profile) | _credential_env_names(profile)
+    for path, data in settings.items():
+        block: Any = data.get(key)
+        if not isinstance(block, dict):
+            continue
+        overridden = sorted(names & set(cast("dict[str, Any]", block)))
+        if overridden:
+            msg = (
+                f"{path} sets {', '.join(overridden)} in its {key!r} block, so "
+                f"{profile.name} does not log in with the caller's environment"
+            )
+            raise HostAuthUnplannableError(HostAuthGap.SETTINGS_ENV, msg)
+
+
+def _external_found(
+    profile: ProviderProfile,
+    source: ExternalCredential,
+    env: Mapping[str, str],
+    home: Path,
+    settings: Mapping[str, dict[str, Any]] | None = None,
+) -> list[str]:
+    """What of *source* is on the host: set variables, existing paths, settings keys."""
+    found = [name for name in source.env if _set(env, name)]
+    found += [path for path in source.paths if (home / path).exists()]
+    if source.settings_keys:
+        loaded = _read_settings(profile, home) if settings is None else settings
+        found += [
+            f"{key} in {path}"
+            for path, data in loaded.items()
+            for key in source.settings_keys
+            if key in data
+        ]
+    return found
+
+
+def _present_names(
+    profile: ProviderProfile,
+    env: Mapping[str, str],
+    home: Path,
+    settings: Mapping[str, dict[str, Any]],
+) -> list[str]:
+    """The names of every declared source present on the host."""
+    names: list[str] = []
+    for source in profile.credential_sources:
+        if isinstance(source, ExternalCredential):
+            names += _external_found(profile, source, env, home, settings)
+        elif _present_kind(source, env, home) is not None:
+            names.append(_name(source))
+    return names
+
+
+def _withheld(
+    profile: ProviderProfile,
+    env: Mapping[str, str],
+    home: Path,
+    present: list[str],
+    delivered: set[str],
+) -> tuple[str, ...]:
+    """The names of the host's auth state a plan delivering *delivered* leaves out."""
+    on_host = {name for name in _host_auth_names(profile) if _set(env, name)}
+    on_host |= {path for path in profile.auth_files if (home / path).is_file()}
+    on_host |= set(present)
+    return tuple(sorted(on_host - delivered))
+
+
+def _delivered(env: Mapping[str, str], files: tuple[StagedCredentialFile, ...]) -> set[str]:
+    return set(env) | {staged.home_path for staged in files}
+
+
+def _credential_env_names(profile: ProviderProfile) -> set[str]:
+    names: set[str] = set()
+    for source in profile.credential_sources:
+        if isinstance(source, EnvCredential):
+            names.add(source.name)
+        elif isinstance(source, ExternalCredential):
+            names.update(source.env)
+    return names
+
+
 def _present_kind(
-    source: CredentialSource, env: Mapping[str, str], home: Path
+    source: _DeliverableSource, env: Mapping[str, str], home: Path
 ) -> CredentialKind | None:
     if isinstance(source, EnvCredential):
         return source.kind if _set(env, source.name) else None
@@ -304,7 +562,7 @@ def _set(env: Mapping[str, str], name: str) -> bool:
     return bool(value and value.strip())
 
 
-def _name(source: CredentialSource) -> str:
+def _name(source: _DeliverableSource) -> str:
     return source.name if isinstance(source, EnvCredential) else source.path
 
 
@@ -326,7 +584,8 @@ def _unavailable(
     wanted = [
         _name(source)
         for source in profile.credential_sources
-        if source.kind is None or source.kind in allowed
+        if not isinstance(source, ExternalCredential)
+        and (source.kind is None or source.kind in allowed)
     ]
     found = f"; present but not allowed: {', '.join(present)}" if present else ""
     return (