agentshim 0.13.1__tar.gz → 0.14.0__tar.gz

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

@@ -1,5 +1,29 @@
 # Changelog
 
+## 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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentshim
-Version: 0.13.1
+Version: 0.14.0
 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.0}/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.0"
 
 __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.0}/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.0}/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.0}/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.0}/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.0}/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.0}/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.0}/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.0}/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.0}/pyproject.toml

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

agentshim-0.14.0/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).