agentshim 0.23.0__tar.gz → 0.24.0__tar.gz

{agentshim-0.23.0 → agentshim-0.24.0}/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## 0.24.0 (2026-10-30)
+
+Everything here is additive. Recorded cost does not move: every price, `price_for`, `cost_usd`,
+`PricingTable` and `ModelPricing` behave as in 0.23.1, and `tests/fixtures/recorded_costs.json`
+(recorded on 0.23.1) proves the costs equal.
+
+### Added
+
+- Pinned prices are generated from a LiteLLM snapshot instead of kept by hand.
+  `scripts/generate_prices.py` reads `tests/fixtures/litellm/snapshot.json` (trimmed to the priced
+  models, with the day it was read and the SHA-256 of the whole file) and writes
+  `providers/{claude,codex}/prices_generated.py`; a test fails if they differ. All 29 rows already
+  matched LiteLLM, so no price changes. `PricingTable.version` is now `litellm-<snapshot date>`
+  (`litellm-2026-10-30`) and every entry's `checked` is that date. The test that every catalogue
+  model is priced or a documented exclusion stays; `gemini-3-pro-preview` is still unpriced.
+- `RateTable`, `RateEntry` and `Rates`: flat per-model rates for estimates, a separate type from the
+  recorded-cost table (a zero rate is allowed, there are fast and ultrafast tiers, and no function
+  takes both kinds). `parse_litellm` reads LiteLLM's price file, `price_tokens` splits a cost by
+  token class, and `speed_premium_usd` and `cache_savings_usd` give the other report figures.
+  `UsageSpeed` is the service speed.
+- `read_rates` and `refresh_rates` keep a rate document fresh for a caller-supplied `RateSource` and
+  `RateStore` (24 hour TTL, 60 second floor that also holds after a failure; an empty or invalid
+  document never replaces a good one). `bundled_rates` is the pinned table with speed tiers, the
+  fallback when nothing was fetched. `rates_for` maps a provider's model names onto the table.
+  agentshim still has no HTTP client. `FakeRateSource`, `FakeRateStore` and `RateStoreContract` are
+  in `agentshim.testing`.
+- `ProviderUsage.by_model`: a `ModelUsage` row for every model a turn ran, with its tokens, its
+  recorded price (the pinned-table price, never the CLI's), the turn's speed and turn count on one
+  primary row. Claude reads it from `modelUsage`, so Task subagents and advisors are visible
+  (`ProviderUsage.tokens` is still the main conversation only, so budgets do not move);
+  `thinkingTokens` fills reasoning. The Codex app-server transport reports one row at the model and
+  service tier the server started the thread with. `merge_model_usage` adds two turns.
+  `ProviderUsage.to_dict` gains a `by_model` key. `CodexScript(service_tier=...)` scripts the tier.
+- `read_transcript_usage`, `transcript_roots` and `transcript_providers`: token usage from the CLIs'
+  own session files, for work done outside agentshim. Claude (`projects/**.jsonl`) and Codex
+  (`sessions` and `archived_sessions`) are read. The reader keeps no state: the caller passes back a
+  `FilePosition` per file and gets only what is new. It resumes only when the file did not shrink
+  and the 64 bytes before the resume point hash the same, otherwise it rereads (`reset`); stops at a
+  line boundary after a byte budget and reports `pending`; skips files by modification time; lists
+  files it cannot read in `failed`; and reduces a line over 8 MiB to the fields it needs. A Claude
+  message repeated per content block counts once; subagent files take their parent's session.
+  `TranscriptSource`, `RateCatalog` and `RateNaming` are new optional plugin capabilities.
+
+## 0.23.1 (2026-10-30)
+
+### Fixed
+
+- `gpt-6.1-sol` has a price. The catalogue listed it since 0.18.2 but the price table did not, so
+  `price_for("codex", "gpt-6.1-sol")` returned `None` and its turns recorded no cost. The rates are
+  the standard short-context tier on https://developers.openai.com/api/docs/pricing, read
+  2026-10-30: input 2.00, cache read 0.10, cache write 2.50, output 10.00 USD per million tokens.
+  The cache read rate is half of `gpt-6-sol`'s. The table version is `2026-10-30`.
+
+### Added
+
+- A test that every model the catalogue or a provider profile lists is priced or named, with its
+  reason, in an exclusion list. `gemini-3-pro-preview` is the one exclusion: Google's pricing page
+  no longer lists it, so no official number can be checked, and Gemini models are not priced.
+
 ## 0.23.0 (2026-10-20)
 
 ### Added

{agentshim-0.23.0 → agentshim-0.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentshim
-Version: 0.23.0
+Version: 0.24.0
 Summary: Provider-agnostic coding-agent CLI shims
 License-Expression: MIT
 License-File: LICENSE
@@ -28,7 +28,10 @@ No required runtime dependencies. Python 3.10+.
 - typed events delivered on the calling thread
 - normalized token accounting (total input, cache reads, cache writes,
   uncached input, output and reasoning) on every provider, plus a static,
-  versioned pricing table (see [Usage and Pricing](docs/pricing.md))
+  versioned pricing table generated from a LiteLLM snapshot (see
+  [Usage and Pricing](docs/pricing.md)), usage by model, list-price estimates
+  from LiteLLM's rates, and usage read from the CLIs' own session files (see
+  [Usage Outside agentshim](docs/transcripts.md))
 - declared capabilities on `ProviderProfile`, so no caller probes a provider
 - injectable `CommandExecutor`s for running the CLI in a container or over a
   remote shell

{agentshim-0.23.0 → agentshim-0.24.0}/README.md

@@ -16,7 +16,10 @@ No required runtime dependencies. Python 3.10+.
 - typed events delivered on the calling thread
 - normalized token accounting (total input, cache reads, cache writes,
   uncached input, output and reasoning) on every provider, plus a static,
-  versioned pricing table (see [Usage and Pricing](docs/pricing.md))
+  versioned pricing table generated from a LiteLLM snapshot (see
+  [Usage and Pricing](docs/pricing.md)), usage by model, list-price estimates
+  from LiteLLM's rates, and usage read from the CLIs' own session files (see
+  [Usage Outside agentshim](docs/transcripts.md))
 - declared capabilities on `ProviderProfile`, so no caller probes a provider
 - injectable `CommandExecutor`s for running the CLI in a container or over a
   remote shell

{agentshim-0.23.0 → agentshim-0.24.0}/agentshim/__init__.py

@@ -36,6 +36,7 @@ from .core import (
     ContinuityError,
     Conversation,
     ConversationSpec,
+    CostBreakdown,
     CostSource,
     CredentialKind,
     CredentialSource,
@@ -45,6 +46,8 @@ from .core import (
     ExternalCredential,
     FailureKind,
     FileCredential,
+    FilePosition,
+    FileScan,
     FlagsInstallation,
     HostAuthGap,
     HostAuthUnplannableError,
@@ -59,6 +62,7 @@ from .core import (
     McpScope,
     McpServer,
     McpTransport,
+    ModelUsage,
     NativeMode,
     NativePermissions,
     NoopInstallation,
@@ -78,7 +82,13 @@ from .core import (
     ProviderStatus,
     ProviderUsage,
     RandomIds,
+    RateCatalog,
+    RateDocumentError,
+    RateEntry,
     RateLimitStatus,
+    RateNaming,
+    Rates,
+    RateTable,
     RawOutput,
     ReapError,
     Reasoning,
@@ -115,6 +125,12 @@ from .core import (
     ToolCall,
     ToolResult,
     ToolTracker,
+    TranscriptFormat,
+    TranscriptParser,
+    TranscriptRecord,
+    TranscriptRoot,
+    TranscriptScan,
+    TranscriptSource,
     Transport,
     TransportKind,
     TurnCancelledError,
@@ -124,6 +140,8 @@ from .core import (
     TurnResult,
     TurnTimeoutError,
     UsageReport,
+    UsageSpeed,
+    cache_savings_usd,
     compact_json,
     compose_event_handlers,
     dialect_problems,
@@ -131,11 +149,15 @@ from .core import (
     install_config_file,
     interactive_env,
     materialize,
+    merge_model_usage,
     normalize,
     normalized_usage,
     parse_json_object,
+    parse_timestamp,
     plan_auth,
     prepare_config_home,
+    price_tokens,
+    speed_premium_usd,
 )
 from .execution import (
     CallbackCommandStreamSink,
@@ -183,10 +205,28 @@ from .providers.codex.app_server import CodexAppServerTransport
 from .providers.copilot import CopilotProvider
 from .providers.gemini import GeminiProvider
 from .providers.opencode import OpencodeProvider
+from .rates import (
+    LITELLM_ENDPOINTS,
+    RATES_TTL,
+    REFRESH_FLOOR,
+    RateEndpoint,
+    RateFetchError,
+    RateRead,
+    RateSnapshot,
+    RateSource,
+    RateStatus,
+    RateStore,
+    bundled_rates,
+    parse_litellm,
+    rates_for,
+    read_rates,
+    refresh_rates,
+)
 from .runtime import Agent
 from .session import Session, Turn, TurnTicket, map_mcp_servers
+from .transcripts import read_transcript_usage, transcript_providers, transcript_roots
 
-__version__ = "0.23.0"
+__version__ = "0.24.0"
 
 __all__ = [  # noqa: RUF022 - public API test uses Python's case-sensitive order
     "Agent",
@@ -235,6 +275,7 @@ __all__ = [  # noqa: RUF022 - public API test uses Python's case-sensitive order
     "Conversation",
     "ConversationSpec",
     "CopilotProvider",
+    "CostBreakdown",
     "CostSource",
     "CredentialKind",
     "CredentialSource",
@@ -246,6 +287,8 @@ __all__ = [  # noqa: RUF022 - public API test uses Python's case-sensitive order
     "ExternalCredential",
     "FailureKind",
     "FileCredential",
+    "FilePosition",
+    "FileScan",
     "FlagsInstallation",
     "GeminiProvider",
     "HostAuthGap",
@@ -255,6 +298,7 @@ __all__ = [  # noqa: RUF022 - public API test uses Python's case-sensitive order
     "HttpMcpServer",
     "IdAllocator",
     "InMemoryCheckpointStore",
+    "LITELLM_ENDPOINTS",
     "Lifecycle",
     "LoginSpec",
     "McpConfigError",
@@ -266,6 +310,7 @@ __all__ = [  # noqa: RUF022 - public API test uses Python's case-sensitive order
     "ModelPricing",
     "ModelSpec",
     "ModelTable",
+    "ModelUsage",
     "NativeMode",
     "NativePermissions",
     "NoRunningTurnError",
@@ -294,8 +339,23 @@ __all__ = [  # noqa: RUF022 - public API test uses Python's case-sensitive order
     "ProviderStatus",
     "ProviderTestSupport",
     "ProviderUsage",
+    "RATES_TTL",
+    "REFRESH_FLOOR",
     "RandomIds",
+    "RateCatalog",
+    "RateDocumentError",
+    "RateEndpoint",
+    "RateEntry",
+    "RateFetchError",
     "RateLimitStatus",
+    "RateNaming",
+    "RateRead",
+    "RateSnapshot",
+    "RateSource",
+    "RateStatus",
+    "RateStore",
+    "RateTable",
+    "Rates",
     "RawOutput",
     "ReapError",
     "Reasoning",
@@ -337,6 +397,12 @@ __all__ = [  # noqa: RUF022 - public API test uses Python's case-sensitive order
     "ToolCall",
     "ToolResult",
     "ToolTracker",
+    "TranscriptFormat",
+    "TranscriptParser",
+    "TranscriptRecord",
+    "TranscriptRoot",
+    "TranscriptScan",
+    "TranscriptSource",
     "TransformingExecutor",
     "Transport",
     "TransportKind",
@@ -349,7 +415,10 @@ __all__ = [  # noqa: RUF022 - public API test uses Python's case-sensitive order
     "TurnTicket",
     "TurnTimeoutError",
     "UsageReport",
+    "UsageSpeed",
     "__version__",
+    "bundled_rates",
+    "cache_savings_usd",
     "compact_json",
     "compose_event_handlers",
     "confine",
@@ -364,14 +433,25 @@ __all__ = [  # noqa: RUF022 - public API test uses Python's case-sensitive order
     "interactive_env",
     "map_mcp_servers",
     "materialize",
+    "merge_model_usage",
     "model_spec",
     "normalize",
     "normalized_usage",
     "parse_json_object",
+    "parse_litellm",
+    "parse_timestamp",
     "plan_auth",
     "prepare_config_home",
     "price_for",
+    "price_tokens",
     "probe_provider",
     "provider_names",
+    "rates_for",
+    "read_rates",
+    "read_transcript_usage",
+    "refresh_rates",
+    "speed_premium_usd",
     "stream_provider_names",
+    "transcript_providers",
+    "transcript_roots",
 ]

{agentshim-0.23.0 → agentshim-0.24.0}/agentshim/core/__init__.py

@@ -98,7 +98,15 @@ from .mcp import (
 )
 from .models import ModelSpec, ModelTable
 from .permissions import ApprovalPolicy, NativeMode, NativePermissions
-from .plugin import ConnectionOptions, PricingContext, ProviderPlugin, ProviderTestSupport
+from .plugin import (
+    ConnectionOptions,
+    PricingContext,
+    ProviderPlugin,
+    ProviderTestSupport,
+    RateCatalog,
+    RateNaming,
+    TranscriptSource,
+)
 from .pricing import ModelPricing, PricingTable, cost_usd
 from .profile import (
     ConfigScope,
@@ -120,13 +128,42 @@ from .provider import (
     Provider,
     StreamParser,
 )
+from .rates import (
+    CostBreakdown,
+    RateDocumentError,
+    RateEntry,
+    Rates,
+    RateTable,
+    cache_savings_usd,
+    price_tokens,
+    speed_premium_usd,
+)
 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 .transcripts import (
+    FilePosition,
+    FileScan,
+    TranscriptFormat,
+    TranscriptParser,
+    TranscriptRecord,
+    TranscriptRoot,
+    TranscriptScan,
+    parse_timestamp,
+)
 from .turn import OutputSchema, TurnRequest, TurnResult
-from .usage import CostSource, ProviderUsage, TokenUsage, TokenWeights, normalized_usage
+from .usage import (
+    CostSource,
+    ModelUsage,
+    ProviderUsage,
+    TokenUsage,
+    TokenWeights,
+    UsageSpeed,
+    merge_model_usage,
+    normalized_usage,
+)
 
 __all__ = [
     "AgentEvent",
@@ -157,6 +194,7 @@ __all__ = [
     "ContinuityError",
     "Conversation",
     "ConversationSpec",
+    "CostBreakdown",
     "CostSource",
     "CredentialKind",
     "CredentialSource",
@@ -166,6 +204,8 @@ __all__ = [
     "ExternalCredential",
     "FailureKind",
     "FileCredential",
+    "FilePosition",
+    "FileScan",
     "FlagsInstallation",
     "HostAuthGap",
     "HostAuthUnplannableError",
@@ -183,6 +223,7 @@ __all__ = [
     "ModelPricing",
     "ModelSpec",
     "ModelTable",
+    "ModelUsage",
     "NativeMode",
     "NativePermissions",
     "NoRunningTurnError",
@@ -205,7 +246,13 @@ __all__ = [
     "ProviderTestSupport",
     "ProviderUsage",
     "RandomIds",
+    "RateCatalog",
+    "RateDocumentError",
+    "RateEntry",
     "RateLimitStatus",
+    "RateNaming",
+    "RateTable",
+    "Rates",
     "RawOutput",
     "ReapError",
     "Reasoning",
@@ -242,6 +289,12 @@ __all__ = [
     "ToolCall",
     "ToolResult",
     "ToolTracker",
+    "TranscriptFormat",
+    "TranscriptParser",
+    "TranscriptRecord",
+    "TranscriptRoot",
+    "TranscriptScan",
+    "TranscriptSource",
     "Transport",
     "TransportKind",
     "TurnCancelledError",
@@ -251,6 +304,8 @@ __all__ = [
     "TurnResult",
     "TurnTimeoutError",
     "UsageReport",
+    "UsageSpeed",
+    "cache_savings_usd",
     "compact_json",
     "compose_event_handlers",
     "cost_usd",
@@ -259,9 +314,13 @@ __all__ = [
     "install_config_file",
     "interactive_env",
     "materialize",
+    "merge_model_usage",
     "normalize",
     "normalized_usage",
     "parse_json_object",
+    "parse_timestamp",
     "plan_auth",
     "prepare_config_home",
+    "price_tokens",
+    "speed_premium_usd",
 ]

{agentshim-0.23.0 → agentshim-0.24.0}/agentshim/core/plugin.py

@@ -20,7 +20,9 @@ if TYPE_CHECKING:
     from .pricing import ModelPricing, PricingTable
     from .profile import ProviderProfile
     from .provider import Provider
+    from .rates import RateTable
     from .status import AuthState, ProviderStatus
+    from .transcripts import TranscriptFormat
     from .usage import TokenUsage
 
 
@@ -170,3 +172,40 @@ class ProviderPlugin(Protocol):
     def test_support(self) -> ProviderTestSupport | None:
         """Return consumer-test adapters, if provided."""
         ...
+
+
+@runtime_checkable
+class RateCatalog(Protocol):
+    """Optional: a plugin that ships rates, with speed tiers, for the models it prices.
+
+    A plugin without it ships none. These are the rates of the pinned table
+    shipped in the wheel, which :func:`agentshim.rates.bundled_rates` collects.
+    """
+
+    def known_rates(self) -> RateTable:
+        """Rates for the models this provider prices."""
+        ...
+
+
+@runtime_checkable
+class RateNaming(Protocol):
+    """Optional: a plugin that knows which flat names a model may be filed under.
+
+    A provider not implementing it gets :func:`agentshim.core.rates.candidate_names`.
+    """
+
+    def rate_names(self, model: str) -> tuple[str, ...]:
+        """Candidate flat names for *model*, most specific first; none if it has no price."""
+        ...
+
+
+@runtime_checkable
+class TranscriptSource(Protocol):
+    """Optional: a plugin whose CLI keeps session files agentshim can read for usage.
+
+    A plugin without it, or answering ``None``, has no readable transcripts.
+    """
+
+    def transcripts(self) -> TranscriptFormat | None:
+        """The format of this provider's session files, or ``None`` if it has none readable."""
+        ...