codex-agent-framework 0.1.58__tar.gz → 0.1.59__tar.gz

{codex_agent_framework-0.1.58 → codex_agent_framework-0.1.59}/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project will be documented in this file.
 
 This project loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and uses semantic versioning where practical.
 
+## [0.1.59] - 2026-05-18
+### Changed
+- Make local context sizing rely on cached local token estimation for messages and tool schemas, with bounded smoothing against observed backend `usage.input_tokens` so status and auto-compaction decisions track reality more closely without a runtime token-counter dependency.
+- Default session compaction to `gpt-5.4-mini` and stop injecting the main agent instructions into compaction requests unless explicit compaction instructions are provided.
+- Bake stable token-count estimates for server tools and keep compact-session usage metadata available for later context accounting.
+
+### Fixed
+- Preserve compaction usage data end-to-end in agent session state so compacted history can reuse backend-observed token accounting when available.
+- Raise the minimum SDK dependency to `codex-backend-sdk>=0.3.5` so compact response usage is available to the agent runtime.
+
+### Tests
+- Add and update focused coverage for local token estimation, correction coefficient behavior, compaction defaults/overrides, compact-session usage accounting, and baked tool token counts.
+
 ## [0.1.58] - 2026-05-17
 ### Fixed
 - Keep active SSE event subscribers attached even when the FastAPI request handler thread that opened the `StreamingResponse` has ended, preventing TUI streams from degrading into ping-only connections that miss real assistant/tool events.

{codex_agent_framework-0.1.58/codex_agent_framework.egg-info → codex_agent_framework-0.1.59}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-agent-framework
-Version: 0.1.58
+Version: 0.1.59
 Summary: A lightweight event-driven Codex agent runtime.
 Author: Baptiste
 License-Expression: MIT
@@ -16,7 +16,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: audioop-lts; python_version >= "3.13"
 Requires-Dist: beautifulsoup4
-Requires-Dist: codex-backend-sdk>=0.3.1
+Requires-Dist: codex-backend-sdk>=0.3.5
 Requires-Dist: fastapi
 Requires-Dist: filetype
 Requires-Dist: modict

{codex_agent_framework-0.1.58 → codex_agent_framework-0.1.59}/codex_agent/agent.py

@@ -461,10 +461,7 @@ class Agent:
                 self.status_manager.invalidate_context_cache()
         messages = self.context_manager.get_context()
         if self.context_manager.should_auto_compact(messages):
-            self.compact_session(
-                model=self.config.model,
-                instructions=self.config_manager.system_message().content,
-            )
+            self.compact_session()
             messages = self.context_manager.get_context()
 
         message = self.ai.run(

{codex_agent_framework-0.1.58 → codex_agent_framework-0.1.59}/codex_agent/ai.py

@@ -248,6 +248,10 @@ class AIClient:
 
         try:
             response_params = self._to_codex_response_params(params)
+            raw_input_estimate = self.agent.context_manager.raw_response_input_token_count(
+                params.get("messages", []),
+                response_tools=params.get("tools") or [],
+            )
             response = self.codex_client.responses.create(**response_params, stream=True)
         except Exception as e:
             if self.is_bad_request_error(e):
@@ -265,8 +269,13 @@ class AIClient:
                 self.agent.mainloop_manager.touch_activity("response_stream")
                 if getattr(event, "type", None) == "response.completed":
                     completed = self._event_response(event)
+                    usage = modict(completed.get("usage") or {})
+                    self.agent.context_manager.apply_token_count_correction(
+                        raw_input_estimate,
+                        usage.get("input_tokens"),
+                    )
                     self.agent.status_manager.cache_api_status(
-                        usage=modict(completed.get("usage") or {}),
+                        usage=usage,
                         model=completed.get("model") or response_params.get("model"),
                         quota=self.get_quota_usage(),
                     )

{codex_agent_framework-0.1.58 → codex_agent_framework-0.1.59}/codex_agent/builtin_commands.py

@@ -38,8 +38,6 @@ def compact(max_compacted_turns=None):
     agent = get_agent()
     max_compacted_turns = None if max_compacted_turns in (None, "", "all") else int(max_compacted_turns)
     message = agent.compact_session(
-        model=agent.config.model,
-        instructions=agent.config_manager.system_message().content,
         max_compacted_turns=max_compacted_turns,
     )
     if message is None:

{codex_agent_framework-0.1.58 → codex_agent_framework-0.1.59}/codex_agent/builtin_plugins/context/__init__.py

@@ -117,8 +117,6 @@ Tool result wrappers expose stable `wrapper_id` values in their XML representati
             max_compacted_turns = int(max_compacted_turns)
         before = self.context_public_status()
         message = self.agent.compact_session(
-            model=self.agent.config.model,
-            instructions=self.agent.config_manager.system_message().content,
             max_compacted_turns=max_compacted_turns,
         )
         after = self.context_public_status()

{codex_agent_framework-0.1.58 → codex_agent_framework-0.1.59}/codex_agent/builtin_plugins/image_generation/__init__.py

@@ -9,6 +9,7 @@ from ...utils import text_content
 
 class ImageGenerationTool(ServerTool):
     type = "image_generation"
+    baked_token_count = 342
     output_format = "png"
     size = None
     quality = None

{codex_agent_framework-0.1.58 → codex_agent_framework-0.1.59}/codex_agent/config.py

@@ -81,6 +81,7 @@ class Config(modict):
 class AgentConfig(Config):
 
     model = "gpt-5.4"
+    compaction_model = "gpt-5.4-mini"
     system = DEFAULT_SYSTEM_PROMPT
     auto_proceed = True
     openai_api_key = None

{codex_agent_framework-0.1.58 → codex_agent_framework-0.1.59}/codex_agent/context.py

@@ -3,12 +3,17 @@ from modict import modict
 from .image import ImageMessage
 from .message import Message, ProviderMessage, SystemMessage, ToolResultWrapper
 from .tool import reset_current_agent, set_current_agent
-from .utils import sort, token_count_payload, truncate
+from .utils import sort, token_count, token_count_payload, truncate
 
 
 class ContextManager:
+    TOKEN_COUNT_COEF_MIN = 0.5
+    TOKEN_COUNT_COEF_MAX = 2.0
+    TOKEN_COUNT_COEF_ALPHA = 0.8
+
     def __init__(self, agent):
         self.agent = agent
+        self.token_count_coef = 1.0
 
     def provider_context_wrapper(self, provider_name, content):
         return f'<context_provider name="{provider_name}">\n{content}\n</context_provider>'
@@ -149,13 +154,6 @@ class ContextManager:
             compactable_messages = 0
             compactable_tokens = 0
         token_count_source = "local_estimate"
-        try:
-            current_count = self.agent.ai.count_input_tokens(
-                **self.response_input_token_payload(formatted_context, response_tools=response_tools)
-            )
-            token_count_source = "openai_input_tokens"
-        except Exception:
-            pass
         input_token_limit = self.agent.config.input_token_limit
         used_token_percent = (current_count / input_token_limit * 100) if input_token_limit else 0
         sent_session_message_percent = (
@@ -216,11 +214,25 @@ class ContextManager:
         return msg.get("turns_left", -1) != 0
 
     def response_tools_token_count(self, response_tools=None):
+        model = self.agent.config.model
         if response_tools is None:
-            response_tools = self.agent.tools_manager.get_response_tools()
+            return self.agent.tools_manager.response_tools_token_count(model=model)
         if not response_tools:
             return 0
-        return token_count_payload({"tools": response_tools}, model=self.agent.config.model)
+        tools = self.agent.tools_manager.get_tools()
+        by_name = {
+            (tool.get("name") or tool.get("type")): tool
+            for tool in tools
+        }
+        total = 0
+        for spec in response_tools:
+            name = spec.get("name") or spec.get("type")
+            tool = by_name.get(name)
+            if tool is not None:
+                total += tool.count_tokens(model=model)
+            else:
+                total += token_count_payload(spec, model=model)
+        return int(total)
 
     def response_input_token_payload(self, messages, response_tools=None):
         instructions = []
@@ -280,23 +292,54 @@ class ContextManager:
 
         return sanitize(payload)
 
-    def response_input_token_count(self, messages, response_tools=None, authoritative=False):
-        payload = self.response_input_token_payload(messages, response_tools=response_tools)
-        if authoritative:
-            try:
-                return self.agent.ai.count_input_tokens(**payload)
-            except Exception:
-                pass
-        media_tokens = sum(
-            msg.api_token_count(model=self.agent.config.model)
-            for msg in messages
-            if isinstance(msg, ImageMessage)
-        )
-        local_tokens = token_count_payload(
-            self.local_token_count_payload(payload),
-            model=self.agent.config.model,
+    def estimate_token_count(self, raw_count):
+        raw_count = int(raw_count or 0)
+        if raw_count <= 0:
+            return 0
+        return max(0, int(round(raw_count * self.token_count_coef)))
+
+    def apply_token_count_correction(self, raw_estimate, observed_input_tokens):
+        raw_estimate = int(raw_estimate or 0)
+        observed_input_tokens = int(observed_input_tokens or 0)
+        if raw_estimate <= 0 or observed_input_tokens <= 0:
+            return self.token_count_coef
+        observed_ratio = observed_input_tokens / raw_estimate
+        observed_ratio = max(self.TOKEN_COUNT_COEF_MIN, min(self.TOKEN_COUNT_COEF_MAX, observed_ratio))
+        new_coef = (
+            self.token_count_coef * self.TOKEN_COUNT_COEF_ALPHA
+            + observed_ratio * (1.0 - self.TOKEN_COUNT_COEF_ALPHA)
         )
-        return local_tokens + media_tokens
+        self.token_count_coef = max(self.TOKEN_COUNT_COEF_MIN, min(self.TOKEN_COUNT_COEF_MAX, new_coef))
+        return self.token_count_coef
+
+    def raw_response_input_token_count(self, messages, response_tools=None):
+        model = self.agent.config.model
+        instructions = []
+        history_messages = []
+        in_instruction_prefix = True
+        for msg in messages:
+            if in_instruction_prefix and isinstance(msg, SystemMessage):
+                instruction = msg.instruction_text()
+                if instruction:
+                    instructions.append(instruction)
+                continue
+            in_instruction_prefix = False
+            history_messages.append(msg)
+
+        instruction_tokens = 0
+        if instructions:
+            instruction_tokens = token_count("\n\n".join(instructions), model=model)
+
+        history_tokens = sum(msg.count_tokens(model=model) for msg in history_messages)
+        tool_tokens = self.response_tools_token_count(response_tools=response_tools)
+        reasoning = self.agent.config.get("reasoning")
+        reasoning_tokens = token_count_payload({"reasoning": modict(reasoning)}, model=model) if reasoning else 0
+        tool_choice_tokens = token_count_payload({"tool_choice": "auto"}, model=model) if response_tools else 0
+        return instruction_tokens + history_tokens + tool_tokens + reasoning_tokens + tool_choice_tokens
+
+    def response_input_token_count(self, messages, response_tools=None):
+        raw_count = self.raw_response_input_token_count(messages, response_tools=response_tools)
+        return self.estimate_token_count(raw_count)
 
     def should_auto_compact(self, messages):
         if not self.agent.config.get("auto_compact", True):

{codex_agent_framework-0.1.58 → codex_agent_framework-0.1.59}/codex_agent/message.py

@@ -36,6 +36,7 @@ class Message(modict):
     timestamp = modict.factory(lambda: timestamp())
     turns_left = -1
     embedding = None
+    token_count = modict.factory(dict)
     estimated_token_count = modict.factory(dict)
 
     def __init__(self, *args, **kwargs):
@@ -91,24 +92,51 @@ class Message(modict):
     def to_response_format(self):
         raise NotImplementedError(f"{type(self).__name__} must implement to_response_format()")
 
-    def api_token_count(self, model=None):
+    def token_count_cache(self):
+        cache = self.get("token_count")
+        if isinstance(cache, dict) and cache:
+            return cache
+        legacy = self.get("estimated_token_count")
+        if isinstance(legacy, dict) and legacy:
+            self.token_count = dict(legacy)
+            return self.token_count
+        self.token_count = {}
+        return self.token_count
+
+    def cache_token_count(self, count, model=None):
+        model_key = str(model or "gpt-5")
+        cache = self.token_count_cache()
+        cache[model_key] = {
+            "fingerprint": self.api_token_fingerprint(),
+            "count": int(count or 0),
+        }
+        self.token_count = cache
+        self.estimated_token_count = dict(cache)
+        return int(count or 0)
+
+    def count_tokens(self, model=None):
         model_key = str(model or "gpt-5")
         fingerprint = self.api_token_fingerprint()
-        cache = self.get("estimated_token_count") or {}
+        cache = self.token_count_cache()
         cached = cache.get(model_key)
         if isinstance(cached, dict) and cached.get("fingerprint") == fingerprint:
             return int(cached.get("count") or 0)
 
-        count = self.compute_api_token_count(model=model)
-        cache[model_key] = {"fingerprint": fingerprint, "count": count}
-        self.estimated_token_count = cache
-        return count
+        count = int(self.compute_api_token_count(model=model) or 0)
+        return self.cache_token_count(count, model=model)
+
+    def api_token_count(self, model=None):
+        return self.count_tokens(model=model)
 
     @modict.computed()
-    def effective_api_token_count(self):
+    def effective_token_count(self):
         if self.get("turns_left", -1) == 0:
             return 0
-        return self.api_token_count()
+        return self.count_tokens()
+
+    @modict.computed()
+    def effective_api_token_count(self):
+        return self.effective_token_count
 
     def api_token_fingerprint(self):
         payload = {
@@ -120,10 +148,21 @@ class Message(modict):
         text = json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":"), default=str)
         return hashlib.sha256(text.encode("utf-8")).hexdigest()
 
+    def token_count_request(self, model=None):
+        item = self.to_response_format()
+        if item is None:
+            return None
+        if isinstance(item, list):
+            return {"model": str(model or "gpt-5"), "input": item}
+        return {"model": str(model or "gpt-5"), "input": [item]}
+
+    def token_count_payload(self):
+        return self.to_response_format()
+
     def compute_api_token_count(self, model=None):
         from .utils import token_count, token_count_payload
 
-        item = self.to_response_format()
+        item = self.token_count_payload()
         if item is None:
             return token_count(str(self.get("content") or ""), model=model)
         return token_count_payload(item, model=model)
@@ -190,6 +229,9 @@ class SystemMessage(TextMessage):
                 parts.append(str(part))
         return "\n".join(part for part in parts if part)
 
+    def token_count_request(self, model=None):
+        return {"model": str(model or "gpt-5"), "instructions": self.instruction_text()}
+
     def compute_api_token_count(self, model=None):
         from .utils import token_count
 
@@ -218,6 +260,7 @@ class CompactionMessage(DeveloperMessage):
     content = "Previous conversation context was compacted by the backend."
     response_id = ""
     summaries = modict.factory(list)
+    usage = modict.factory(modict)
     compacted_message_count = 0
 
     def __init__(self, *args, **kwargs):
@@ -238,6 +281,39 @@ class CompactionMessage(DeveloperMessage):
     def to_response_format(self):
         return list(self.get("summaries") or [])
 
+    def observed_token_count(self):
+        usage = self.get("usage") or {}
+        if not isinstance(usage, dict):
+            return None
+        for key in ("input_tokens", "max_input_tokens"):
+            value = usage.get(key)
+            if isinstance(value, int) and value >= 0:
+                return value
+        return None
+
+    def count_tokens(self, model=None):
+        observed = self.observed_token_count()
+        if observed is not None:
+            return int(observed)
+        return super().count_tokens(model=model)
+
+    def token_count_request(self, model=None):
+        if self.observed_token_count() is not None:
+            return None
+        payload = self.token_count_payload()
+        if not payload:
+            return {"model": str(model or "gpt-5"), "input": []}
+        return {"model": str(model or "gpt-5"), "input": payload}
+
+    def token_count_payload(self):
+        sanitized = []
+        for item in self.get("summaries") or []:
+            entry = dict(item)
+            if entry.get("type") == "compaction_summary" and entry.get("encrypted_content"):
+                entry["encrypted_content"] = "<encrypted_compaction_summary>"
+            sanitized.append(entry)
+        return sanitized
+
     def as_string_attrs(self):
         attrs = self.extract('name', 'type', 'timestamp')
         attrs["response_id"] = self.get("response_id")

{codex_agent_framework-0.1.58 → codex_agent_framework-0.1.59}/codex_agent/sessions.py

@@ -151,7 +151,7 @@ class AgentSession(modict):
         self,
         client=None,
         model="gpt-5.4",
-        instructions="",
+        instructions=None,
         max_input_tokens=DEFAULT_COMPACTION_MAX_INPUT_TOKENS,
         max_compacted_turns=None,
     ):
@@ -165,15 +165,26 @@ class AgentSession(modict):
             return None
 
         history = self.messages_to_response_history(plan.history_messages)
-        client = client or CodexClient(model=model, instructions=instructions).authenticate()
-        result = client.responses.compact(
+        client_kwargs = modict(model=model)
+        if instructions is not None:
+            client_kwargs.instructions = instructions
+        client = client or CodexClient(**client_kwargs).authenticate()
+        compact_params = modict(
             input=history,
             model=model,
-            instructions=instructions,
         )
+        if instructions is not None:
+            compact_params.instructions = instructions
+        result = client.responses.compact(**compact_params)
+        usage = getattr(result, "usage", None)
+        if hasattr(usage, "model_dump"):
+            usage = usage.model_dump()
+        elif usage is not None and not isinstance(usage, dict):
+            usage = dict(usage)
         message = CompactionMessage(
             response_id=result.id,
             summaries=CompactionMessage.summary_items(result.output),
+            usage=usage or {},
             compacted_message_count=len(compacted_messages),
             compacted_turn_count=plan.compacted_turn_count,
             preserved_turn_count=plan.preserved_turn_count,
@@ -797,9 +808,7 @@ class SessionsManager:
                 max_compacted_turns=max_compacted_turns,
             ).wait().result
 
-        model = model or self.agent.config.model
-        if instructions is None:
-            instructions = self.agent.config_manager.system_message().content
+        model = model or self.agent.config.get("compaction_model") or self.agent.config.model
         max_input_tokens = self.agent.config.get(
             "max_input_tokens",
             DEFAULT_COMPACTION_MAX_INPUT_TOKENS,
@@ -821,9 +830,10 @@ class SessionsManager:
         )
         compact_kwargs = modict(
             model=model,
-            instructions=instructions,
             max_input_tokens=max_input_tokens,
         )
+        if instructions is not None:
+            compact_kwargs.instructions = instructions
         if max_compacted_turns is not None:
             compact_kwargs.max_compacted_turns = max_compacted_turns
         if client is not None:

codex_agent_framework-0.1.59/codex_agent/token_counter.py

@@ -0,0 +1,115 @@
+class TokenCounter:
+    """Count tokens for a single object using minimal Responses input_tokens requests.
+
+    The counter is object-oriented: each supported object provides a
+    ``token_count_request(model=...)`` projection and stores its own cached
+    result locally in ``token_count``.
+    """
+
+    def __init__(self, ai, default_model="gpt-5", baseline_text="PING"):
+        self.ai = ai
+        self.default_model = default_model
+        self.baseline_text = baseline_text
+        self._baseline_counts = {}
+
+    def count_object(self, obj, model=None):
+        model = str(model or self.default_model or "gpt-5")
+
+        cached = self._cached_count(obj, model=model)
+        if cached is not None:
+            return cached
+
+        observed = self._observed_count(obj)
+        if observed is not None:
+            return self._store_count(obj, observed, model=model)
+
+        request = getattr(obj, "token_count_request", lambda model=None: None)(model=model)
+        if request is None:
+            if hasattr(obj, "count_tokens"):
+                return int(obj.count_tokens(model=model))
+            raise TypeError(f"{type(obj).__name__} does not support token counting")
+
+        if self._needs_baseline(request):
+            baseline = self._baseline_request(model=model)
+            baseline_count = self._baseline_count(model=model)
+            payload = dict(request)
+            payload["input"] = baseline["input"]
+            count = int(self.ai.count_input_tokens(**payload)) - baseline_count
+        else:
+            count = int(self.ai.count_input_tokens(**request))
+        return self._store_count(obj, count, model=model)
+
+    def hydrate(self, objects, model=None):
+        return [self.count_object(obj, model=model) for obj in objects]
+
+    def _baseline_request(self, model=None):
+        return {
+            "model": str(model or self.default_model or "gpt-5"),
+            "input": [{
+                "type": "message",
+                "role": "user",
+                "content": [{"type": "input_text", "text": self.baseline_text}],
+            }],
+        }
+
+    def _baseline_count(self, model=None):
+        model_key = str(model or self.default_model or "gpt-5")
+        cached = self._baseline_counts.get(model_key)
+        if cached is not None:
+            return int(cached)
+        count = int(self.ai.count_input_tokens(**self._baseline_request(model=model_key)))
+        self._baseline_counts[model_key] = count
+        return count
+
+    def _needs_baseline(self, request):
+        if not isinstance(request, dict):
+            return False
+        payload_input = request.get("input")
+        if payload_input:
+            return False
+        return True
+
+    def _observed_count(self, obj):
+        observed = getattr(obj, "observed_token_count", None)
+        if callable(observed):
+            value = observed()
+            if value is not None:
+                return int(value)
+        return None
+
+    def _fingerprint(self, obj):
+        if hasattr(obj, "api_token_fingerprint"):
+            return obj.api_token_fingerprint()
+        if hasattr(obj, "response_tool_fingerprint"):
+            return obj.response_tool_fingerprint()
+        return None
+
+    def _cache_map(self, obj):
+        token_count_cache = getattr(obj, "token_count_cache", None)
+        if callable(token_count_cache):
+            return token_count_cache()
+        getter = getattr(obj, "get", None)
+        if callable(getter):
+            cache = getter("token_count") or {}
+            return cache if isinstance(cache, dict) else {}
+        return {}
+
+    def _cached_count(self, obj, model=None):
+        model_key = str(model or self.default_model or "gpt-5")
+        fingerprint = self._fingerprint(obj)
+        cache = self._cache_map(obj)
+        cached = cache.get(model_key)
+        if not isinstance(cached, dict):
+            return None
+        if fingerprint is not None and cached.get("fingerprint") != fingerprint:
+            return None
+        if "count" not in cached:
+            return None
+        return int(cached.get("count") or 0)
+
+    def _store_count(self, obj, count, model=None):
+        count = int(count or 0)
+        cache_method = getattr(obj, "cache_token_count", None)
+        if callable(cache_method):
+            return int(cache_method(count, model=model))
+        return count