codex-agent-framework 0.1.78__tar.gz → 0.1.80__tar.gz

{codex_agent_framework-0.1.78 → codex_agent_framework-0.1.80}/CHANGELOG.md

@@ -4,6 +4,13 @@ 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.80] - 2026-05-18
+### Changed
+- Document `AgentClient` event-stream, SSE parsing, sequence resume, URL, and HTTP request helper contracts with concise docstrings.
+
+### Tests
+- Validate the client documentation pass with targeted client tests plus the full offline CI suite (618 passed).
+
 ## [0.1.60] - 2026-05-18
 ### Fixed
 - Count compacted summary messages with observed compaction `usage.output_tokens` instead of `usage.input_tokens`, so future context estimates reflect the size of the produced summary rather than the size of the compacted input.

{codex_agent_framework-0.1.78/codex_agent_framework.egg-info → codex_agent_framework-0.1.80}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-agent-framework
-Version: 0.1.78
+Version: 0.1.80
 Summary: A lightweight event-driven Codex agent runtime.
 Author: Baptiste
 License-Expression: MIT

{codex_agent_framework-0.1.78 → codex_agent_framework-0.1.80}/codex_agent/builtin_plugins/content/vision.py

@@ -96,6 +96,7 @@ def observe(sources):
 
 
 def normalize_observe_source(source):
+    """Normalize legacy string sources and mapping sources to observe objects."""
     if isinstance(source, str):
         target = "url" if source.startswith(("http://", "https://")) else "path"
         key = "url" if target == "url" else "path"
@@ -106,6 +107,7 @@ def normalize_observe_source(source):
 
 
 def observe_source(source):
+    """Dispatch one normalized observe source to the matching capture helper."""
     item = normalize_observe_source(source)
     if not item:
         return "failed: source must be an object."
@@ -123,6 +125,7 @@ def observe_source(source):
 
 
 def resolve_agent_path(path):
+    """Resolve paths relative to the active agent when one is available."""
     try:
         return get_agent().resolve_path(path)
     except RuntimeError:
@@ -130,6 +133,7 @@ def resolve_agent_path(path):
 
 
 def observe_path(item):
+    """Validate a local image path observe source."""
     path = item.get("path") or item.get("source")
     if not isinstance(path, str) or not path:
         return "failed: path target requires a non-empty 'path'."
@@ -138,6 +142,7 @@ def observe_path(item):
 
 
 def observe_url(item):
+    """Observe a URL as an image, falling back to a page screenshot."""
     url = item.get("url") or item.get("source")
     if not isinstance(url, str) or not url:
         return "failed: url target requires a non-empty 'url'."
@@ -161,6 +166,7 @@ def observe_url(item):
 
 
 def observe_screen(item):
+    """Capture and validate a screenshot of the local screen."""
     output_path = item.get("output_path")
     if output_path:
         output_path = resolve_agent_path(output_path)
@@ -172,6 +178,7 @@ def observe_screen(item):
 
 
 def observe_window(item):
+    """Capture and validate a screenshot of a local desktop window."""
     window_id = item.get("window_id") or item.get("id")
     output_path = item.get("output_path")
     if output_path:
@@ -184,6 +191,7 @@ def observe_window(item):
 
 
 def validated_image(path, image_name=None, original_source=None, url_fallback=False):
+    """Return an ImageMessage or a readable failure string for invalid input."""
     image = ImageMessage(content=path, image_name=image_name, turns_left=3)
     if not image.is_valid():
         label = "URL fallback screenshot" if url_fallback else "image source"
@@ -192,6 +200,7 @@ def validated_image(path, image_name=None, original_source=None, url_fallback=Fa
 
 
 def screenshot_page_url(url, item=None):
+    """Capture a webpage screenshot using caller options or a runtime path."""
     item = item or {}
     path = item.get("output_path")
     if path:

{codex_agent_framework-0.1.78 → codex_agent_framework-0.1.80}/codex_agent/cli/root.py

@@ -22,6 +22,7 @@ ROOT_COMMANDS = {
 
 
 def build_root_parser():
+    """Build the public root CLI parser and command dispatcher options."""
     import argparse
 
     parser = argparse.ArgumentParser(

{codex_agent_framework-0.1.78 → codex_agent_framework-0.1.80}/codex_agent/client.py

@@ -276,6 +276,7 @@ class AgentClient:
                     self._event_stop.wait(0.1)
 
     def event_error_payload(self, exc):
+        """Build a local client error event from an event-stream exception."""
         payload = modict(type="client_event_error", error=str(exc), source="event_stream")
         if isinstance(exc, requests.HTTPError) and exc.response is not None:
             payload.status_code = exc.response.status_code
@@ -289,11 +290,13 @@ class AgentClient:
         return payload
 
     def is_event_idle_timeout(self, exc):
+        """Return whether an event-stream exception is an idle read timeout."""
         if isinstance(exc, (requests.exceptions.ReadTimeout, requests.exceptions.Timeout)):
             return True
         return "read timed out" in str(exc).lower()
 
     def iter_sse(self, lines):
+        """Yield parsed SSE payloads from decoded or byte line chunks."""
         event = None
         data_lines = []
         event_id = None
@@ -339,6 +342,7 @@ class AgentClient:
             yield payload
 
     def remember_event_sequence(self, event):
+        """Track the highest numeric event sequence seen for replay resume."""
         sequence = event.get("sequence") if isinstance(event, dict) else None
         if sequence is None:
             return
@@ -348,17 +352,22 @@ class AgentClient:
             return
         if self._last_event_sequence is None or sequence > self._last_event_sequence:
             self._last_event_sequence = sequence
+
     def events_url(self):
+        """Build the SSE endpoint URL with replay and compaction parameters."""
         params = {"client_pid": int(self.client_pid)}
         if self.compact_events:
             params["compact"] = 1
         if self._last_event_sequence is not None:
             params["after_sequence"] = int(self._last_event_sequence)
         return self.url(f"/events?{urlencode(params)}")
+
     def url(self, path):
+        """Return an absolute server URL for an API path."""
         return self.base_url + path
 
     def request(self, method, path, **kwargs):
+        """Send an HTTP request and decode its JSON response as a modict."""
         kwargs.setdefault("timeout", self.timeout)
         response = requests.request(method, self.url(path), **kwargs)
         response.raise_for_status()
@@ -367,12 +376,15 @@ class AgentClient:
         return modict(response.json())
 
     def get(self, path):
+        """Send a GET request to a server API path."""
         return self.request("GET", path)
 
     def post(self, path, payload=None):
+        """Send a JSON POST request to a server API path."""
         return self.request("POST", path, json=payload or {})
 
     def delete(self, path):
+        """Send a DELETE request to a server API path."""
         return self.request("DELETE", path)
 
     def health(self):

codex_agent_framework-0.1.80/codex_agent/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.80"

{codex_agent_framework-0.1.78 → codex_agent_framework-0.1.80/codex_agent_framework.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-agent-framework
-Version: 0.1.78
+Version: 0.1.80
 Summary: A lightweight event-driven Codex agent runtime.
 Author: Baptiste
 License-Expression: MIT

{codex_agent_framework-0.1.78 → codex_agent_framework-0.1.80}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codex-agent-framework"
-version = "0.1.78"
+version = "0.1.80"
 description = "A lightweight event-driven Codex agent runtime."
 readme = "README.md"
 requires-python = ">=3.11"

codex_agent_framework-0.1.78/codex_agent/version.py

@@ -1 +0,0 @@
-__version__ = "0.1.78"