agentshim 0.6.8__tar.gz → 0.8.0__tar.gz

{agentshim-0.6.8 → agentshim-0.8.0}/CHANGELOG.md

@@ -1,5 +1,96 @@
 # Changelog
 
+## 0.8.0 (2026-10-03)
+
+Skill observability. Additive: a caller that ignores the new events and the
+new `TurnResult` field sees no change, but an exhaustive match over
+`AgentEvent` gains two members.
+
+### Added
+
+- `SkillsDiscovered(names)` and `SkillInvoked(name, source_path, tool_id)`
+  events. `SkillInvoked` sits directly after the `ToolCall` that loaded the
+  skill.
+- `TurnResult.skills`: a `SkillSummary` (`discovered`, `invocations`,
+  `invoked`, `invocation_count`) folded from those events by `SkillTracker`,
+  which callers can also register as a handler to cover several turns.
+  `None` means unknown, never zero.
+- `ProviderProfile.skill_discovery` and `skill_invocation`, each a
+  `SkillSignal` (`NONE`, `STRUCTURED`, `INFERRED`).
+- Claude Code: discovery from the `system/init` `skills` list; a load is a
+  `Skill` tool call or a `Read` of a `SKILL.md`.
+- Codex: a load is inferred from a shell command that names a `SKILL.md`
+  under a `skills/` directory. `codex exec --json` does not list offered
+  skills, so discovery is unknown.
+- Gemini, opencode and Copilot report unknown for both.
+- `scripted_turn(..., skills_offered=[...], skills_invoked=[...])` scripts the
+  offered list (Claude) and skill loads (Claude, Codex) in each provider's own
+  format; a provider whose stream cannot carry them raises `ValueError`.
+- Recorded skill streams under `tests/fixtures/{claude,codex}/` and a live
+  e2e suite, `tests/e2e/test_skills_e2e.py`, with a positive and a negative
+  turn per provider.
+
+### Fixed
+
+- `normalize(schema, SchemaDialect.STRICT)` no longer closes an open map
+  (`additionalProperties` a schema or `true`), which silently turned
+  `dict[str, float]` into an object that can only be empty. The map is kept
+  and `dialect_problems` on the normalized schema reports it, so
+  `dialect_problems(normalize(s, d), d) == []` is the check for whether a
+  generated schema can go native.
+
+## 0.7.0 (2026-09-27)
+
+First-class cache accounting and a static pricing table. Additive except one
+change of meaning: `cached_input_tokens` now counts cache reads only (see
+Changed).
+
+### Added
+
+- `TokenUsage.cache_read_input_tokens` (input served from the prompt cache),
+  `cache_write_1h_input_tokens` (the one-hour-TTL part of cache writes, from
+  Claude's `cache_creation` breakdown) and the derived
+  `uncached_input_tokens` (`input - cache_read - cache_write`). `to_dict()`
+  gains the three keys; no key was removed.
+- Codex turns now report `cache_write_input_tokens` and
+  `reasoning_output_tokens` from `turn.completed` (both used to be dropped).
+- `TokenUsage` checks its invariants on construction:
+  `cache_read + cache_write <= input`, `cache_write_1h <= cache_write`,
+  `reasoning <= output`, no negative counts. Parsers build it through the new
+  `normalized_usage`, which clamps a CLI's inconsistent counts instead.
+- `TokenUsage.from_dict` reads a `to_dict()` mapping back, including one
+  written before 0.7.0.
+- `TokenWeights` and `TokenUsage.weighted_total(weights)`: a total weighted by
+  token class (uncached input, cache reads, 5m and 1h cache writes, output,
+  reasoning), each token weighted once.
+- A static, versioned pricing table (`agentshim.core.pricing`):
+  `ModelPricing`, `PricingTable`, `default_pricing()`,
+  `price_for(provider, model, table=None)` (`None` for an unknown model, never
+  zero), `cost_usd(usage, pricing)` and `ModelPricing.relative_weights()`.
+  It covers OpenAI GPT-6 (astra, sol, luna), GPT-5.6, GPT-5.5 and earlier
+  GPT-5 models, and Claude Fable 5.1, Fable 5, Opus 5.5, Opus 5, Opus 4.8,
+  Sonnet 5, Sonnet 4.6 and Haiku 4.5, each with its official source URL and
+  check date (all 2026-09-27). Callers override or extend it with
+  `PricingTable.with_entries` or `PricingTable.from_dict`. Holding prices in
+  agentshim is a user-directed decision; see `docs/pricing.md`.
+- Recorded Codex, Claude (5m and 1h cache writes), opencode and Gemini
+  streams under `tests/fixtures/`, with tests pinning each provider's mapping.
+  The Claude Haiku 4.5 recording's `total_cost_usd` is reproduced exactly by
+  the table.
+
+### Changed
+
+- `cached_input_tokens` is a deprecated alias of `cache_read_input_tokens`.
+  On Claude, opencode and Copilot it used to be reads plus writes; it is now
+  reads only, since a cache write is billed above base input and a read far
+  below it. Codex and Gemini report no writes in their cached count, so their
+  value is unchanged. Constructing with `cached_input_tokens=` still works.
+
+### Documented
+
+- Claude's `result.usage` covers the main conversation only; a Task
+  subagent's tokens appear only in `modelUsage` and `total_cost_usd`.
+
 ## 0.6.8 (2026-09-27)
 
 A tightening of the Codex (`STRICT`) schema check: schemas it now rejects

{agentshim-0.6.8 → agentshim-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentshim
-Version: 0.6.8
+Version: 0.8.0
 Summary: Provider-agnostic coding-agent CLI shims
 Requires-Python: >=3.10
 Provides-Extra: test
@@ -23,8 +23,9 @@ No required runtime dependencies. Python 3.10+.
 
 - `CliAgent` / `AgentSession`: one turn at a time, resumable, cancellable
 - typed events delivered on the calling thread
-- normalized token accounting where `cached_input_tokens <= input_tokens` on
-  every provider
+- 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))
 - 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.6.8 → agentshim-0.8.0}/README.md

@@ -14,8 +14,9 @@ No required runtime dependencies. Python 3.10+.
 
 - `CliAgent` / `AgentSession`: one turn at a time, resumable, cancellable
 - typed events delivered on the calling thread
-- normalized token accounting where `cached_input_tokens <= input_tokens` on
-  every provider
+- 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))
 - 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.6.8 → agentshim-0.8.0}/agentshim/__init__.py

@@ -29,11 +29,13 @@ from .core import (
     McpMechanism,
     McpServer,
     McpTransport,
+    ModelPricing,
     NoopInstallation,
     NullEventHandler,
     OutputSchema,
     OutputSchemaStyle,
     ParsedTurn,
+    PricingTable,
     Provider,
     ProviderCapabilityError,
     ProviderError,
@@ -47,10 +49,16 @@ from .core import (
     SchemaDialectError,
     SessionResumeError,
     SessionStarted,
+    SkillInvoked,
+    SkillsDiscovered,
+    SkillSignal,
+    SkillSummary,
+    SkillTracker,
     Stderr,
     StdioMcpServer,
     StreamParser,
     TokenUsage,
+    TokenWeights,
     ToolCall,
     ToolResult,
     ToolTracker,
@@ -59,12 +67,16 @@ from .core import (
     UsageReport,
     compact_json,
     compose_event_handlers,
+    cost_usd,
+    default_pricing,
     dialect_problems,
     install_config_file,
     interactive_env,
     materialize,
     normalize,
+    normalized_usage,
     parse_json_object,
+    price_for,
 )
 from .execution import (
     CallbackCommandStreamSink,
@@ -84,7 +96,7 @@ from .providers.copilot import CopilotProvider
 from .providers.gemini import GeminiProvider
 from .providers.opencode import OpencodeProvider
 
-__version__ = "0.6.8"
+__version__ = "0.8.0"
 
 __all__ = [
     "AgentEvent",
@@ -123,6 +135,7 @@ __all__ = [
     "McpMechanism",
     "McpServer",
     "McpTransport",
+    "ModelPricing",
     "NoopInstallation",
     "NullEventHandler",
     "NullSink",
@@ -130,6 +143,7 @@ __all__ = [
     "OutputSchema",
     "OutputSchemaStyle",
     "ParsedTurn",
+    "PricingTable",
     "Provider",
     "ProviderCapabilityError",
     "ProviderError",
@@ -144,10 +158,16 @@ __all__ = [
     "SchemaDialectError",
     "SessionResumeError",
     "SessionStarted",
+    "SkillInvoked",
+    "SkillSignal",
+    "SkillSummary",
+    "SkillTracker",
+    "SkillsDiscovered",
     "Stderr",
     "StdioMcpServer",
     "StreamParser",
     "TokenUsage",
+    "TokenWeights",
     "ToolCall",
     "ToolResult",
     "ToolTracker",
@@ -158,12 +178,16 @@ __all__ = [
     "__version__",
     "compact_json",
     "compose_event_handlers",
+    "cost_usd",
+    "default_pricing",
     "dialect_problems",
     "get_provider",
     "install_config_file",
     "interactive_env",
     "materialize",
     "normalize",
+    "normalized_usage",
     "parse_json_object",
+    "price_for",
     "provider_names",
 ]

{agentshim-0.6.8 → agentshim-0.8.0}/agentshim/agent.py

@@ -26,6 +26,7 @@ from agentshim.core.events import RunFinished, RunStarted, compose_event_handler
 from agentshim.core.profile import McpMechanism, OutputSchemaStyle, SchemaDialect
 from agentshim.core.provider import ArgvContext
 from agentshim.core.schema import compact_json, dialect_problems, materialize
+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
@@ -278,8 +279,10 @@ class AgentSession:
         agent = self._agent
         handler = agent.event_handler
         resumed = self.session_id is not None
+        skills = SkillTracker(self.profile)
 
         def emit(event: AgentEvent) -> None:
+            skills.on_event(event)
             handler.on_event(event)
 
         argv = list(command.argv)
@@ -305,6 +308,7 @@ class AgentSession:
             cost_usd=parsed.cost_usd,
             duration_ms=duration_ms,
             exit_code=result.returncode,
+            skills=skills.summary(),
         )
         self.last_result = turn_result
         return turn_result

{agentshim-0.6.8 → agentshim-0.8.0}/agentshim/core/__init__.py

@@ -34,6 +34,8 @@ from .events import (
     RunFinished,
     RunStarted,
     SessionStarted,
+    SkillInvoked,
+    SkillsDiscovered,
     Stderr,
     ToolCall,
     ToolResult,
@@ -50,12 +52,20 @@ from .mcp import (
     StdioMcpServer,
     install_config_file,
 )
-from .profile import McpMechanism, OutputSchemaStyle, ProviderProfile, SchemaDialect
+from .pricing import ModelPricing, PricingTable, cost_usd, default_pricing, price_for
+from .profile import (
+    McpMechanism,
+    OutputSchemaStyle,
+    ProviderProfile,
+    SchemaDialect,
+    SkillSignal,
+)
 from .provider import ArgvContext, McpInstallation, ParsedTurn, Provider, StreamParser
 from .schema import compact_json, dialect_problems, materialize, normalize
+from .skills import SkillSummary, SkillTracker
 from .stream import ToolTracker, parse_json_object
 from .turn import OutputSchema, TurnRequest, TurnResult
-from .usage import ProviderUsage, TokenUsage
+from .usage import ProviderUsage, TokenUsage, TokenWeights, normalized_usage
 
 __all__ = [
     "AgentEvent",
@@ -79,11 +89,13 @@ __all__ = [
     "McpMechanism",
     "McpServer",
     "McpTransport",
+    "ModelPricing",
     "NoopInstallation",
     "NullEventHandler",
     "OutputSchema",
     "OutputSchemaStyle",
     "ParsedTurn",
+    "PricingTable",
     "Provider",
     "ProviderCapabilityError",
     "ProviderError",
@@ -97,10 +109,16 @@ __all__ = [
     "SchemaDialectError",
     "SessionResumeError",
     "SessionStarted",
+    "SkillInvoked",
+    "SkillSignal",
+    "SkillSummary",
+    "SkillTracker",
+    "SkillsDiscovered",
     "Stderr",
     "StdioMcpServer",
     "StreamParser",
     "TokenUsage",
+    "TokenWeights",
     "ToolCall",
     "ToolResult",
     "ToolTracker",
@@ -109,10 +127,14 @@ __all__ = [
     "UsageReport",
     "compact_json",
     "compose_event_handlers",
+    "cost_usd",
+    "default_pricing",
     "dialect_problems",
     "install_config_file",
     "interactive_env",
     "materialize",
     "normalize",
+    "normalized_usage",
     "parse_json_object",
+    "price_for",
 ]

{agentshim-0.6.8 → agentshim-0.8.0}/agentshim/core/events.py

@@ -74,6 +74,34 @@ class ToolResult:
     duration_s: float | None
 
 
+@dataclass(frozen=True)
+class SkillsDiscovered:
+    """The provider listed the skills it offers this session.
+
+    ``names`` are the skill names as the provider reports them (a plugin
+    skill may carry a ``plugin:`` prefix). Only emitted by a provider whose
+    profile declares ``skill_discovery`` other than ``SkillSignal.NONE``, and
+    only when its stream actually carried the list.
+    """
+
+    names: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class SkillInvoked:
+    """The agent loaded a skill's instructions.
+
+    Emitted at the point in the stream where the load happened, directly
+    after the ``ToolCall`` that performed it; ``tool_id`` names that call.
+    ``source_path`` is the skill file or directory when the stream reveals
+    it, and ``None`` otherwise.
+    """
+
+    name: str
+    source_path: str | None = None
+    tool_id: str | None = None
+
+
 @dataclass(frozen=True)
 class UsageReport:
     """Provider accounting for the turn so far."""
@@ -119,6 +147,8 @@ AgentEvent = (
     | Reasoning
     | ToolCall
     | ToolResult
+    | SkillsDiscovered
+    | SkillInvoked
     | UsageReport
     | Lifecycle
     | Stderr
@@ -351,6 +381,8 @@ class ConsoleEventHandler:
         """
         if isinstance(event, Stderr):
             self._line(f"[stderr] {event.text.rstrip()}")
+        elif isinstance(event, SkillInvoked):
+            self._line(self._paint(f"[Skill] {event.name}", self._BLUE))
         elif isinstance(event, ProviderError):
             self._line(f"[error] {event.message}")
         elif isinstance(event, Lifecycle) and self._show_lifecycle: