agentshim 0.23.1__tar.gz → 0.24.1__tar.gz

{agentshim-0.23.1 → agentshim-0.24.1}/CHANGELOG.md

@@ -1,5 +1,121 @@
 # Changelog
 
+## 0.24.1 (2026-10-31)
+
+Fixes the usage numbers 0.24.0 got wrong. Recorded cost does not move for any single-result turn:
+every price, `price_for` and `cost_usd` are as in 0.24.0, and `tests/fixtures/recorded_costs.json`
+still proves it.
+
+### Fixed
+
+- **Claude transcripts undercounted output by about a third.** The CLI writes one line per content
+  block of a message, and the lines do not repeat the same usage: the prompt side is identical, but
+  `output_tokens` grows as the reply streams, from a few tokens on the first line to the whole reply
+  on the last. 0.24.0 kept the first line and dropped the rest. A message is now counted once, at
+  the most any line reported, and the records of a message add up to its final usage: the first
+  line yields the request (`turns=1`), each later line yields only the tokens it added (`turns=0`,
+  usually only output). Sum tokens over records, and count requests by summing `turns`. An advisor
+  call that shows only on a later line is counted too. A position saved by 0.24.0 has no such
+  counts, so it is refused and the file is read again from the start (`reset`), which also corrects
+  what 0.24.0 missed.
+- **`ProviderUsage.by_model` counted the first turn after a steer twice.** `modelUsage` is
+  cumulative over the CLI process, and the parser added each result's rows to the last. The rows of
+  a run are now those of its last result, which cover the run once, and the rows sum to
+  `total_cost_usd`. The same seam is fixed for the primary row's `turns` (the run's, not the last
+  result's) and for the one-hour share of cache writes (the run's, applied to the run's writes), so a
+  steered run whose results differ in cache TTL is no longer priced at the last result's share.
+  A single result is unchanged.
+- **A moved Codex session file was counted twice.** Codex archives a rollout by moving it from
+  `sessions` to `archived_sessions` under the same name. agentshim now owns that: a file with the
+  name of one already read is read on from the furthest position held for it (after the usual check
+  of the bytes before that position), and a copy that is shorter than what was read holds nothing
+  new. Keep one `known` mapping for all roots of a provider, as before. A caller no longer
+  de-duplicates anything. **Removed:** `TranscriptRoot.shared_sessions` and
+  `TranscriptFormat.shared_sessions`, which only told the caller to do this itself; a format sets
+  `session_file` (the name every copy of a session's file has) instead.
+- **A fetched LiteLLM document took known prices away.** It replaced the pinned table whole, so a
+  model LiteLLM dropped or renamed lost its estimate, and a row listed at zero before its price was
+  known turned a known price into $0. A document is now laid over the pinned table: a model it lacks
+  keeps its pinned rates, a row with no input or output price does not replace a pinned price, and a
+  speed tier with no price under a priced standard is dropped. A model only the document knows is
+  taken as listed, free or not. `RateRead.known_models` counts the result.
+- A `modelUsage` key with no name no longer raises out of the parser; its tokens are the row
+  `unknown`, which has no price, so the turn is `UNKNOWN_MODEL` as in 0.23.1. The CLI's
+  `<synthetic>` placeholder bills nothing and no longer makes a turn `UNKNOWN_MODEL`.
+- `ultrafast` is read as `UsageSpeed.ULTRAFAST` in a Claude result and in a transcript (it read as
+  none, and as standard). A speed agentshim has no name for is still `None` (read as standard).
+- `read_rates` and `refresh_rates` reject a naive `now` with `ValueError` before anything is
+  fetched. A clock set back is tolerated: a time stamped ahead of `now` by more than the floor has an
+  unknown age and counts as expired (it was fresh until the clock caught up), and an attempt more than
+  the floor away no longer holds off a refresh.
+- The Codex app-server transport skips the `by_model` row of a model name that is blank.
+
+### Changed
+
+- `read_transcript_usage(..., include_cwd=False)`: records carry `cwd` only when asked. It is an
+  absolute path on the user's machine, so a record a caller stores or sends holds no personal path by
+  default.
+- `ModelUsage.recorded_usd` is documented as what it was: the pinned table's standard-tier list
+  price, no bill. A row whose `speed` is fast or ultrafast was billed more; docs/pricing.md shows
+  how to price the tier with `rates_for`, `price_tokens` and `speed_premium_usd`. Recorded cost still
+  does not model speed tiers.
+- docs/transcripts.md states that `since` selects files, not records (filter on `timestamp`), and
+  that a line is held in memory whole while it is read.
+
+### Added
+
+- Tests built from data shaped like what the CLIs write, not idealised input:
+  `tests/unit/transcripts/shapes.py` (streamed Claude messages whose output grows, advisor calls
+  that show late, Codex session files that grow, move and are copied),
+  `tests/unit/stream_shapes.py` (a steered Claude process with cumulative `modelUsage`),
+  `tests/unit/rate_shapes.py` (partial, renamed and placeholder LiteLLM documents), and a synthetic
+  session file shaped like a real streamed message (`tests/fixtures/claude_session`). Properties over
+  them: records summed over any read split equal the final usage; a moved or copied session is
+  counted once; steered results equal one result of the whole run; no known price becomes 0.
+
+## 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

{agentshim-0.23.1 → agentshim-0.24.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentshim
-Version: 0.23.1
+Version: 0.24.1
 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.1 → agentshim-0.24.1}/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.1 → agentshim-0.24.1}/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.1"
+__version__ = "0.24.1"
 
 __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.1 → agentshim-0.24.1}/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.1 → agentshim-0.24.1}/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."""
+        ...