agentshim 0.13.1__tar.gz → 0.14.1__tar.gz

{agentshim-0.13.1 → agentshim-0.14.1}/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.14.1 (2026-10-04)
+
+### Fixed
+
+- Schema normalization preserves descriptions, titles and examples, including
+  annotations alongside `$ref`, so structured-output field guidance reaches
+  the model. Only metadata rejected by the selected dialect is removed.
+- The open schema dialect accepts `oneOf` variants, as Claude does.
+
+## 0.14.0 (2026-10-04)
+
+Codex resumed turns report invocation usage. Additive.
+
+### Added
+
+- `ProviderUsage.increment_known` marks whether the invocation's token
+  increment is measurable. Unknown increments retain raw cumulative usage
+  and zero token placeholders; consumers must check the marker before
+  pricing or budgeting.
+- `previous_usage` on session creation and adoption seeds a checkpointed
+  conversation's usage baseline. `ParserContext` and `ContextualStreamParser`
+  let providers receive invocation context without changing provider factories.
+
+### Fixed
+
+- Codex `turn.completed` usage is cumulative per thread. Resumed turns now
+  subtract the prior raw usage report for every token class instead of
+  counting earlier tokens again. Repeated completion snapshots replace the
+  previous snapshot, and conversations retain independent baselines,
+  including after failed invocations.
+- Package `__version__` and its test now match the project metadata; the
+  0.13.1 release left both at 0.13.0.
+
 ## 0.13.1 (2026-10-03)
 
 Fix only.

{agentshim-0.13.1 → agentshim-0.14.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentshim
-Version: 0.13.1
+Version: 0.14.1
 Summary: Provider-agnostic coding-agent CLI shims
 Requires-Python: >=3.10
 Requires-Dist: tomli>=2; python_full_version < '3.11'

{agentshim-0.13.1 → agentshim-0.14.1}/agentshim/__init__.py

@@ -21,6 +21,7 @@ from .core import (
     ConfigFileInstallation,
     ConfigScope,
     ConsoleEventHandler,
+    ContextualStreamParser,
     EventHandlerBase,
     FailureKind,
     FlagsInstallation,
@@ -38,6 +39,7 @@ from .core import (
     OutputSchema,
     OutputSchemaStyle,
     ParsedTurn,
+    ParserContext,
     PricingTable,
     Provider,
     ProviderCapabilityError,
@@ -101,7 +103,7 @@ from .providers.copilot import CopilotProvider
 from .providers.gemini import GeminiProvider
 from .providers.opencode import OpencodeProvider
 
-__version__ = "0.13.0"
+__version__ = "0.14.1"
 
 __all__ = [
     "AgentEvent",
@@ -129,6 +131,7 @@ __all__ = [
     "ConfigFileInstallation",
     "ConfigScope",
     "ConsoleEventHandler",
+    "ContextualStreamParser",
     "CopilotProvider",
     "EventHandlerBase",
     "FailureKind",
@@ -151,6 +154,7 @@ __all__ = [
     "OutputSchema",
     "OutputSchemaStyle",
     "ParsedTurn",
+    "ParserContext",
     "PricingTable",
     "Provider",
     "ProviderCapabilityError",

{agentshim-0.13.1 → agentshim-0.14.1}/agentshim/agent.py

@@ -31,7 +31,7 @@ from agentshim.core.profile import (
     SchemaDialect,
     SkillScope,
 )
-from agentshim.core.provider import ArgvContext
+from agentshim.core.provider import ArgvContext, ContextualStreamParser, ParserContext
 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
@@ -46,6 +46,7 @@ if TYPE_CHECKING:
     from agentshim.core.profile import ProviderProfile
     from agentshim.core.provider import McpInstallation, ParsedTurn, Provider, StreamParser
     from agentshim.core.turn import OutputSchema
+    from agentshim.core.usage import ProviderUsage
     from agentshim.execution.executor import CommandExecutor, CommandHandle, CommandResult
 
 
@@ -121,6 +122,7 @@ class CliAgent:
         cwd: str | None = None,
         timeout: float | None = None,
         session_id: str | None = None,
+        previous_usage: ProviderUsage | None = None,
         skill_scope: SkillScope = SkillScope.ALL,
         mcp_scope: McpScope = McpScope.ALL,
         config_scope: ConfigScope = ConfigScope.ALL,
@@ -128,13 +130,16 @@ class CliAgent:
         """Open a conversation whose turns resume one another.
 
         ``skill_scope``, ``mcp_scope`` and ``config_scope`` are fixed for the
-        conversation (see ``AgentSession``).
+        conversation (see ``AgentSession``). ``previous_usage`` seeds the
+        baseline when adopting a cumulative-usage provider conversation after
+        a restart; pass its most recent ``TurnResult.usage``.
         """
         return AgentSession(
             self,
             cwd=cwd,
             timeout=timeout,
             session_id=session_id,
+            previous_usage=previous_usage,
             skill_scope=skill_scope,
             mcp_scope=mcp_scope,
             config_scope=config_scope,
@@ -175,6 +180,7 @@ class AgentSession:
         cwd: str | None = None,
         timeout: float | None = None,
         session_id: str | None = None,
+        previous_usage: ProviderUsage | None = None,
         skill_scope: SkillScope = SkillScope.ALL,
         mcp_scope: McpScope = McpScope.ALL,
         config_scope: ConfigScope = ConfigScope.ALL,
@@ -185,7 +191,9 @@ class AgentSession:
         successive turns resume one another. ``cwd`` and ``timeout`` are
         defaults an individual ``TurnRequest`` may override. Passing
         ``session_id`` adopts a conversation the provider already has, so the
-        first turn resumes rather than starts fresh. ``skill_scope`` limits
+        first turn resumes rather than starts fresh. ``previous_usage`` is
+        that conversation's last report, including raw cumulative totals,
+        when it was run outside this session. ``skill_scope`` limits
         which skills every turn's CLI may discover; a scope the provider's
         ``profile.skill_scopes`` does not list raises
         ``ProviderCapabilityError`` here, before any turn runs. ``mcp_scope``
@@ -215,6 +223,9 @@ class AgentSession:
         self._timeout = timeout
         self.session_id: str | None = session_id
         self.last_result: TurnResult | None = None
+        self._usage_by_session: dict[str, ProviderUsage] = {}
+        if session_id is not None and previous_usage is not None:
+            self._usage_by_session[session_id] = previous_usage
         self._lock = threading.Lock()
         self._handle: CommandHandle | None = None
         self._cancel_requested = False
@@ -230,9 +241,11 @@ class AgentSession:
         """
         return self._agent.profile
 
-    def adopt(self, session_id: str) -> bool:
+    def adopt(self, session_id: str, *, previous_usage: ProviderUsage | None = None) -> bool:
         """Continue an existing provider conversation on the next turn.
 
+        ``previous_usage`` seeds an external conversation's last raw report.
+        Reports from conversations already seen by this session are retained.
         Returns ``False`` when the provider cannot resume, or when a turn is
         in flight and switching conversations would race it.
         """
@@ -242,6 +255,8 @@ class AgentSession:
             if not self._idle.is_set():
                 return False
             self.session_id = session_id
+            if previous_usage is not None:
+                self._usage_by_session[session_id] = previous_usage
         return True
 
     def forget(self) -> bool:
@@ -348,7 +363,19 @@ class AgentSession:
             handler.on_event(event)
 
         argv = list(command.argv)
-        parser = agent.provider.new_parser(emit, expect_structured=expect_structured)
+        parser = agent.provider.new_parser(
+            emit,
+            expect_structured=expect_structured,
+        )
+        if isinstance(parser, ContextualStreamParser):
+            parser.configure(
+                ParserContext(
+                    previous_usage=(
+                        self._usage_by_session.get(self.session_id) if self.session_id else None
+                    ),
+                    resumed=resumed,
+                )
+            )
         emit(RunStarted(tuple(argv)))
         started = time.monotonic()
         try:
@@ -359,6 +386,7 @@ class AgentSession:
         duration_ms = int((time.monotonic() - started) * 1000)
         emit(RunFinished(result.returncode))
         parsed = parser.finish()
+        self._remember_usage(parsed)
         self._adopt_then_report(parsed, result, argv, resumed=resumed)
 
         turn_result = TurnResult(
@@ -393,11 +421,18 @@ class AgentSession:
         """
         emit(RunFinished(None))
         partial = parser.finish()
+        self._remember_usage(partial)
         if partial.session_id:
             self.session_id = partial.session_id
         if isinstance(error, CliTimeoutError):
             error.partial = partial
 
+    def _remember_usage(self, parsed: ParsedTurn) -> None:
+        """Retain raw totals even on a failed invocation, without erasing a baseline."""
+        session_id = parsed.session_id or self.session_id
+        if session_id is not None and parsed.usage.raw is not None:
+            self._usage_by_session[session_id] = parsed.usage
+
     def _adopt_then_report(
         self,
         parsed: ParsedTurn,

{agentshim-0.13.1 → agentshim-0.14.1}/agentshim/core/__init__.py

@@ -65,7 +65,15 @@ from .profile import (
     SkillScope,
     SkillSignal,
 )
-from .provider import ArgvContext, McpInstallation, ParsedTurn, Provider, StreamParser
+from .provider import (
+    ArgvContext,
+    ContextualStreamParser,
+    McpInstallation,
+    ParsedTurn,
+    ParserContext,
+    Provider,
+    StreamParser,
+)
 from .schema import compact_json, dialect_problems, materialize, normalize
 from .skills import SkillSummary, SkillTracker
 from .stream import ToolTracker, parse_json_object
@@ -86,6 +94,7 @@ __all__ = [
     "ConfigFileInstallation",
     "ConfigScope",
     "ConsoleEventHandler",
+    "ContextualStreamParser",
     "EventHandlerBase",
     "FailureKind",
     "FlagsInstallation",
@@ -103,6 +112,7 @@ __all__ = [
     "OutputSchema",
     "OutputSchemaStyle",
     "ParsedTurn",
+    "ParserContext",
     "PricingTable",
     "Provider",
     "ProviderCapabilityError",

{agentshim-0.13.1 → agentshim-0.14.1}/agentshim/core/provider.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any, Protocol
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
 
 from .errors import FailureKind
 from .profile import ConfigScope, McpScope, SkillScope
@@ -99,6 +99,23 @@ class StreamParser(Protocol):
         ...
 
 
+@dataclass(frozen=True)
+class ParserContext:
+    """Optional invocation context for parsers that need cumulative usage."""
+
+    previous_usage: ProviderUsage | None = None
+    resumed: bool = False
+
+
+@runtime_checkable
+class ContextualStreamParser(Protocol):
+    """Optional parser extension, leaving existing provider factories compatible."""
+
+    def configure(self, context: ParserContext) -> None:
+        """Set invocation context once, before any stream lines are fed."""
+        ...
+
+
 class McpInstallation(Protocol):
     """The undo record for MCP servers installed for one turn."""
 
@@ -140,7 +157,9 @@ class Provider(Protocol):
 
         A parser is single-use. ``expect_structured`` says the caller asked for
         an output schema, which is what lets a parser tell a missing structured
-        result apart from a turn that never wanted one.
+        result apart from a turn that never wanted one. Parsers that implement
+        ``ContextualStreamParser`` receive a ``ParserContext`` before streaming.
+        Existing parsers need not implement that optional extension.
         """
         ...
 

{agentshim-0.13.1 → agentshim-0.14.1}/agentshim/core/schema.py

@@ -2,7 +2,9 @@
 
 Providers disagree about which JSON Schema subset their structured-output
 flag accepts, and the failure mode is an expensive agent turn that ends in a
-CLI parse error. These checks run before the process starts.
+CLI parse error. These checks run before the process starts. Real CLI probes
+on 2026-10-04 confirmed that Codex and Claude accept descriptions, titles
+and examples; normalization preserves these annotations as model guidance.
 """
 
 from __future__ import annotations
@@ -30,8 +32,6 @@ UNSUPPORTED_KEYWORDS = frozenset(
         "$anchor",
         "$dynamicAnchor",
         "$dynamicRef",
-        "$id",
-        "$schema",
         "allOf",
         "contains",
         "dependentRequired",
@@ -41,7 +41,6 @@ UNSUPPORTED_KEYWORDS = frozenset(
         "maxContains",
         "minContains",
         "not",
-        "oneOf",
         "patternProperties",
         "prefixItems",
         "propertyNames",
@@ -53,17 +52,28 @@ UNSUPPORTED_KEYWORDS = frozenset(
 
 _SUBSCHEMA_MAPS = frozenset({"properties", "$defs", "definitions"})
 
-# Annotations that describe a schema rather than constrain a value. They are
-# what a generator such as Pydantic emits alongside the real constraints, and
-# what the strictest CLI subset refuses to read, so ``normalize`` removes
-# them. Field names are never matched against this set: ``properties`` is
-# traversed as a map of subschemas, so a property named ``title`` survives.
+# Metadata values are annotations or document identifiers, never subschemas.
+# Preserve model guidance, including annotations alongside a $ref. Field
+# names are never matched against this set: properties is a subschema map.
 _METADATA_KEYWORDS = frozenset({"$schema", "$id", "title", "description", "examples"})
 
-# ``$schema`` and ``$id`` identify the dialect and the document; a CLI that
-# accepts open-ended schemas ignores them rather than failing on them. Codex's
-# ``--output-schema`` subset does not, so ``STRICT`` keeps reporting them.
-_OPEN_DIALECT_TOLERATES = frozenset({"$schema", "$id"})
+# Dialect policy is shared by checking and normalization. Codex's strict
+# subset rejects document identifiers; open schemas tolerate them. Neither
+# dialect rejects description/title/examples in the measured CLI versions.
+_REJECTED_METADATA: dict[SchemaDialect, frozenset[str]] = {
+    SchemaDialect.STRICT: frozenset({"$schema", "$id"}),
+    SchemaDialect.OPEN: frozenset(),
+}
+
+# Claude accepts oneOf variants, while Codex's strict subset rejects oneOf.
+_DIALECT_UNSUPPORTED = {
+    SchemaDialect.STRICT: UNSUPPORTED_KEYWORDS | {"oneOf"},
+    SchemaDialect.OPEN: UNSUPPORTED_KEYWORDS,
+}
+_REF_ANNOTATIONS_ALLOWED = {
+    SchemaDialect.STRICT: False,
+    SchemaDialect.OPEN: True,
+}
 
 # Keywords whose values are data, never subschemas. ``required`` is a list of
 # field names and ``enum``/``const`` hold instance values, so a name such as
@@ -84,7 +94,10 @@ def dialect_problems(schema: Mapping[str, Any], dialect: SchemaDialect) -> list[
     ``additionalProperties: false`` and lists exactly its ``properties`` in
     ``required`` (an optional value is
     expressed as nullable instead), the root is not an ``anyOf``, and every
-    ``$ref`` resolves inside the document.
+    ``$ref`` resolves inside the document. Real CLI probes on 2026-10-04
+    confirmed both dialects accept ``description``, ``title`` and ``examples``
+    on schema nodes. ``STRICT`` rejects them beside ``$ref``; ``OPEN`` accepts
+    those siblings and ``oneOf`` variants.
     """
     root = dict(schema)
     walk = _Walk(root=root, dialect=dialect, problems=[])
@@ -125,9 +138,9 @@ class _Walk:
     def visit(self, node: object, location: str) -> None:
         """Walk one schema node, appending a problem for every unsupported construct.
 
-        A ``$ref`` node terminates the walk: its siblings are annotations the
-        strict subset ignores, and the target is checked where it is defined,
-        since every local target is inside the document this walk covers.
+        A ``$ref`` node terminates the walk after checking its metadata. The
+        target is checked where it is defined, since every local target is
+        inside the document this walk covers.
         """
         if isinstance(node, list):
             for index, value in enumerate(cast("list[object]", node)):
@@ -140,6 +153,7 @@ class _Walk:
         reference = mapping.get("$ref")
         if reference is not None:
             self._check_ref(reference, location)
+            self._check_ref_metadata(mapping, location)
             return
 
         if not self._check_properties_shape(mapping, location):
@@ -157,6 +171,17 @@ class _Walk:
         if self.dialect is SchemaDialect.STRICT and not _resolves(self.root, reference):
             self.problems.append(f"{location} has a $ref {reference!r} that resolves to nothing")
 
+    def _check_ref_metadata(self, mapping: dict[str, Any], location: str) -> None:
+        """Check metadata siblings without traversing the referenced target twice."""
+        for key in mapping:
+            if key not in _METADATA_KEYWORDS:
+                continue
+            if (
+                key in _REJECTED_METADATA[self.dialect]
+                or not _REF_ANNOTATIONS_ALLOWED[self.dialect]
+            ):
+                self.problems.append(f"{location} uses unsupported keyword {key!r} beside '$ref'")
+
     def _check_properties_shape(self, mapping: dict[str, Any], location: str) -> bool:
         """Check that ``properties``, if present, is an object.
 
@@ -220,9 +245,9 @@ class _Walk:
         for key, value in mapping.items():
             if key in _SUBSCHEMA_MAPS:
                 self._visit_subschema_map(value, f"{location}/{key}")
-            elif key in UNSUPPORTED_KEYWORDS:
-                if self.dialect is not SchemaDialect.STRICT and key in _OPEN_DIALECT_TOLERATES:
-                    continue
+            elif (
+                key in _DIALECT_UNSUPPORTED[self.dialect] or key in _REJECTED_METADATA[self.dialect]
+            ):
                 self.problems.append(f"{location} uses unsupported keyword {key!r}")
             elif key in _METADATA_KEYWORDS or key in _NON_SCHEMA_KEYWORDS:
                 # Annotations or plain values: nothing below them is a schema.
@@ -269,10 +294,13 @@ def normalize(schema: Mapping[str, Any], dialect: SchemaDialect) -> dict[str, An
     Generators such as Pydantic omit defaulted properties from ``required``
     and leave ``additionalProperties`` unset, which the CLIs read as "any
     subset of these keys, plus anything else". This closes every object,
-    requires every declared property, drops ``default``, strips the annotation
-    siblings of a ``$ref`` that the strict subset forbids, and removes the
-    document metadata (``$schema``, ``$id``, ``title``, ``description``,
-    ``examples``) that ``dialect_problems`` reports under ``STRICT``. An open
+    requires every declared property and drops ``default``. Descriptions,
+    titles and examples are retained at every schema node: Codex and Claude
+    accepted them in real CLI probes on 2026-10-04. For ``STRICT``, annotations
+    beside ``$ref`` move to an ``anyOf`` wrapper containing the reference;
+    ``OPEN`` keeps them as siblings.
+    Only metadata rejected by the dialect is removed (``$schema`` and ``$id``
+    under ``STRICT``). Other ``$ref`` siblings are stripped as before. An open
     map (``additionalProperties`` a schema or ``true``) is kept, since closing
     it would change what the schema accepts; so ``dialect_problems`` on the
     normalized schema reports exactly what the dialect cannot express.
@@ -290,10 +318,10 @@ def _normalized(node: object, dialect: SchemaDialect) -> object:
 
     reference = mapping.get("$ref")
     if isinstance(reference, str):
-        return {"$ref": reference}
+        return _normalized_ref(mapping, dialect, reference)
 
     mapping.pop("default", None)
-    for annotation in _METADATA_KEYWORDS:
+    for annotation in _REJECTED_METADATA[dialect]:
         mapping.pop(annotation, None)
     properties = mapping.get("properties")
     if isinstance(properties, dict):
@@ -305,6 +333,8 @@ def _normalized(node: object, dialect: SchemaDialect) -> object:
         mapping["required"] = []
 
     for key, value in list(mapping.items()):
+        if key in _METADATA_KEYWORDS or key in _NON_SCHEMA_KEYWORDS:
+            continue
         if key in _SUBSCHEMA_MAPS and isinstance(value, dict):
             mapping[key] = {
                 name: _normalized(subschema, dialect)
@@ -315,6 +345,20 @@ def _normalized(node: object, dialect: SchemaDialect) -> object:
     return mapping
 
 
+def _normalized_ref(
+    mapping: dict[str, Any], dialect: SchemaDialect, reference: str
+) -> dict[str, Any]:
+    """Keep accepted annotations without introducing forbidden $ref siblings."""
+    annotations = {
+        key: value
+        for key, value in mapping.items()
+        if key in _METADATA_KEYWORDS - _REJECTED_METADATA[dialect]
+    }
+    if annotations and not _REF_ANNOTATIONS_ALLOWED[dialect]:
+        return {"anyOf": [{"$ref": reference}], **annotations}
+    return {"$ref": reference, **annotations}
+
+
 def _close_object(mapping: dict[str, Any], dialect: SchemaDialect) -> None:
     """Close an object whose extra keys are merely unspecified.
 

{agentshim-0.13.1 → agentshim-0.14.1}/agentshim/core/usage.py

@@ -267,12 +267,17 @@ class ProviderUsage:
 
     ``raw`` keeps the last usage mapping the CLI printed so a caller can
     diagnose a normalization gap without re-parsing the stream.
+    ``increment_known=False`` means the invocation's token increment could
+    not be reconstructed (for example, a Codex resume without a baseline).
+    Its token counts are zero placeholders, with ``turns`` still counted;
+    callers must check this marker before pricing or budgeting the counts.
     """
 
     tokens: TokenUsage = field(default_factory=TokenUsage)
     total_cost_usd: float | None = None
     provider: str = ""
     raw: Mapping[str, Any] | None = None
+    increment_known: bool = True
 
     def to_dict(self) -> dict[str, Any]:
         """Flatten the normalized counts, cost, and provider name into one mapping.
@@ -284,4 +289,5 @@ class ProviderUsage:
             **self.tokens.to_dict(),
             "total_cost_usd": self.total_cost_usd,
             "provider": self.provider,
+            "increment_known": self.increment_known,
         }

{agentshim-0.13.1 → agentshim-0.14.1}/agentshim/providers/codex/events.py

@@ -34,7 +34,7 @@ class TurnStarted:
 
 @dataclass(frozen=True)
 class TurnCompleted:
-    """``{"type":"turn.completed","usage":{...}}``: one turn's token counts.
+    """``{"type":"turn.completed","usage":{...}}``: cumulative thread token counts.
 
     Codex's ``input_tokens`` already includes ``cached_input_tokens`` (cache
     reads) and ``cache_write_input_tokens``, and ``output_tokens`` already

{agentshim-0.13.1 → agentshim-0.14.1}/agentshim/providers/codex/parser.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+from dataclasses import replace
 from typing import TYPE_CHECKING
 
 from agentshim.core.events import (
@@ -17,7 +18,7 @@ from agentshim.core.events import (
     ToolResult,
     UsageReport,
 )
-from agentshim.core.provider import ParsedTurn
+from agentshim.core.provider import ParsedTurn, ParserContext
 from agentshim.core.stream import ToolTracker, parse_json_object
 from agentshim.core.usage import ProviderUsage, TokenUsage, normalized_usage
 
@@ -53,20 +54,20 @@ COMMAND_TOOL = "execute"
 FAILED_ITEM_STATUS = "failed"
 
 
-def fold_usage(frame: TurnCompleted, previous: TokenUsage) -> TokenUsage:
-    """Add one ``turn.completed`` frame's counts to the running total.
+def fold_usage(frame: TurnCompleted, previous: TurnCompleted) -> TokenUsage:
+    """Subtract the previous thread total from Codex's cumulative counts.
 
-    Codex's counts are already nested the way agentshim normalizes them:
-    ``input_tokens`` includes cache reads (``cached_input_tokens``) and cache
-    writes, and ``output_tokens`` includes ``reasoning_output_tokens``. So
-    unlike Claude nothing is folded in; adding them would double-count.
+    Exec JSON exports the thread's total, including on resume, with no
+    per-invocation field. Input already includes cache reads and writes;
+    output already includes reasoning. Subtract before normalizing so an
+    inconsistent provider breakdown cannot distort the saved baseline.
     """
-    return previous + normalized_usage(
-        input_tokens=frame.input_tokens,
-        output_tokens=frame.output_tokens,
-        cache_read_input_tokens=frame.cached_input_tokens,
-        cache_write_input_tokens=frame.cache_write_input_tokens,
-        reasoning_output_tokens=frame.reasoning_output_tokens,
+    return normalized_usage(
+        input_tokens=frame.input_tokens - previous.input_tokens,
+        output_tokens=frame.output_tokens - previous.output_tokens,
+        cache_read_input_tokens=frame.cached_input_tokens - previous.cached_input_tokens,
+        cache_write_input_tokens=frame.cache_write_input_tokens - previous.cache_write_input_tokens,
+        reasoning_output_tokens=frame.reasoning_output_tokens - previous.reasoning_output_tokens,
         turns=1,
     )
 
@@ -79,6 +80,8 @@ class CodexStreamParser:
         emit: Callable[[AgentEvent], None],
         *,
         expect_structured: bool = False,
+        previous_usage: ProviderUsage | None = None,
+        resumed: bool = False,
     ) -> None:
         """Build a parser that emits through *emit*.
 
@@ -86,6 +89,10 @@ class CodexStreamParser:
             emit: Sink for every event this run produces.
             expect_structured: Whether the turn asked Codex for a schema, in
                 which case the final message is decoded as JSON.
+            previous_usage: The prior invocation's report. Its raw counts,
+                rather than its normalized increment, are the thread baseline.
+            resumed: Whether this invocation resumes an existing thread. A
+                completed resume without a baseline cannot be accounted for.
         """
         self._emit = emit
         self._expect_structured = expect_structured
@@ -94,11 +101,30 @@ class CodexStreamParser:
         # Codex has no terminal result frame: the last agent_message is the
         # answer, and with a schema it is the structured payload verbatim.
         self._final_text: str | None = None
+        self.configure(ParserContext(previous_usage=previous_usage, resumed=resumed))
+        self._completed_turns = 0
         self._tokens = TokenUsage()
-        self._usage = ProviderUsage(provider=PROVIDER_NAME)
         self._error: str | None = None
         self._stderr: list[str] = []
 
+    def configure(self, context: ParserContext) -> None:
+        """Set the fixed starting baseline before streaming this invocation."""
+        baseline = None
+        if (
+            context.previous_usage is not None
+            and context.previous_usage.provider == PROVIDER_NAME
+            and context.previous_usage.raw is not None
+        ):
+            baseline = parse_frame(
+                {"type": "turn.completed", "usage": dict(context.previous_usage.raw)}
+            )
+        self._baseline = baseline if isinstance(baseline, TurnCompleted) else TurnCompleted()
+        self._baseline_known = not context.resumed or (
+            isinstance(baseline, TurnCompleted) and baseline.usage is not None
+        )
+
+        self._usage = ProviderUsage(provider=PROVIDER_NAME, increment_known=self._baseline_known)
+
     def feed_stdout(self, line: str) -> None:
         """Parse one stdout line, emitting whatever events it carries."""
         data = parse_json_object(line)
@@ -159,12 +185,18 @@ class CodexStreamParser:
         self._emit(Lifecycle("thread_started", frame.thread_id))
 
     def _turn_completed(self, frame: TurnCompleted) -> None:
-        self._tokens = fold_usage(frame, self._tokens)
+        self._completed_turns += 1
+        if frame.usage is not None and self._baseline_known:
+            delta = fold_usage(frame, self._baseline)
+            self._tokens = replace(delta, turns=self._completed_turns)
+        else:
+            self._tokens = self._tokens + TokenUsage(turns=1)
         self._usage = ProviderUsage(
             tokens=self._tokens,
             total_cost_usd=None,
             provider=PROVIDER_NAME,
             raw=frame.usage if frame.usage is not None else self._usage.raw,
+            increment_known=self._baseline_known,
         )
         if frame.usage is None:
             self._emit(Lifecycle("turn_completed", ""))

{agentshim-0.13.1 → agentshim-0.14.1}/agentshim/providers/codex/provider.py

@@ -188,7 +188,10 @@ class CodexProvider:
         expect_structured: bool,
     ) -> CodexStreamParser:
         """Build a stream parser for one run."""
-        return CodexStreamParser(emit, expect_structured=expect_structured)
+        return CodexStreamParser(
+            emit,
+            expect_structured=expect_structured,
+        )
 
     def install_mcp(self, workspace: Path | None, servers: Sequence[McpServer]) -> McpInstallation:
         """Render *servers* as ``--config mcp_servers.*`` flags.

{agentshim-0.13.1 → agentshim-0.14.1}/agentshim/providers/codex/scripted.py

@@ -40,7 +40,8 @@ def scripted_lines(  # noqa: PLR0913
     Args:
         text: The assistant's final message.
         session_id: Thread id announced by ``thread.started``.
-        usage: Token counts reported by ``turn.completed``.
+        usage: Cumulative thread counts reported by ``turn.completed``.
+            For a resumed turn, include the earlier invocations too.
         tool_calls: Commands to report as started-then-completed items.
         structured_output: Payload to serialize as the final message.
         skills_offered: Must be None; the stream lists no offered skills.

{agentshim-0.13.1 → agentshim-0.14.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentshim"
-version = "0.13.1"
+version = "0.14.1"
 description = "Provider-agnostic coding-agent CLI shims"
 readme = "README.md"
 requires-python = ">=3.10"

agentshim-0.14.1/tests/fixtures/codex/README.md

@@ -0,0 +1,18 @@
+# Codex usage fixtures
+
+The existing `exec_gpt6_luna.jsonl` and skill fixtures are recorded CLI stdout.
+Their usage mappings are unchanged.
+
+`resume_vibesys_totals.jsonl` is a minimal reconstruction of the two input
+counts supplied in the VibeSys bug report: 2,019,100 followed by 12,564,014
+for the same thread. The thread id is synthetic. Output, cache and reasoning
+counts were not supplied, so these fields are omitted rather than invented.
+This is not a newly recorded CLI run. Codex 0.160.0 was found on the
+interactive shell's PATH, but the requested `gpt-6.1-sol` / medium probe
+failed to initialize its app-server because the unchanged Codex home is
+read-only in this sandbox. It emitted no JSON events. The repository
+contained no two-invocation recording.
+
+Codex 0.144.4's JSON event processor copies all five fields from the thread
+usage `total` into `turn.completed.usage`; it does not expose a per-turn field:
+[provider source](https://github.com/openai/codex/blob/rust-v0.144.4/codex-rs/exec/src/event_processor_with_jsonl_output.rs).