codex-agent-framework 0.1.13__tar.gz → 0.1.15__tar.gz

{codex_agent_framework-0.1.13 → codex_agent_framework-0.1.15}/CHANGELOG.md

@@ -4,6 +4,41 @@ 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.15] - 2026-05-08
+### Added
+- Add `AgentRuntime` as the canonical external runtime contract for HTTP server, headless CLI, in-process, and process-backed integrations.
+- Add structured runtime configuration updates through `PATCH /config`, `AgentClient.update_config()`, and `codex-agent config set`.
+- Add direct built-in selection config for tools, providers, and plugins with `None` meaning all built-ins, an empty list meaning none, and explicit lists selecting named built-ins.
+
+### Changed
+- Split the command line implementation into the `codex_agent.cli` package with root orchestration commands and headless runtime commands.
+- Route server operations through `AgentRuntime` instead of depending on `Agent` internals directly.
+- Update CLI service/interface commands to the explicit `start/stop/restart server|tray` and `open/close tui` forms.
+
+### Tests
+- Add regression coverage for the runtime abstraction, headless CLI, root CLI dispatch, config updates, and built-in selection.
+- Validate the targeted release-regression suite at 82 passing tests.
+
+## [0.1.14] - 2026-05-07
+### Added
+- Add a general `HookManager` with compatibility helpers and hook sites around message submission, commands, context/provider calls, runtime module loading, tool calls, shell execution, and file write/edit operations.
+- Add planner and scheduler built-in plugins with atomic JSON persistence safeguards.
+- Add `dependencies.txt` documenting non-Python system dependencies for browser, desktop, tray, service, TUI terminal, and audio features.
+- Add packaged system dependency installation via `codex-agent install-system-deps` and a higher-level `codex-agent bootstrap` command that can install system dependencies then install/start the user services.
+
+### Changed
+- Improve TUI SSE replay/reconnect handling so replayed deltas are rendered as a compact catch-up while live deltas continue streaming normally.
+- Keep the TUI reconnection status concise by reporting one offline message per outage and a connected message on recovery.
+
+### Fixed
+- Fix SSE cursor tracking so client replay state advances only from real sequenced events, avoiding missed events after reconnects.
+- Surface asynchronous memory archive failures through `MemoryArchiveErrorEvent` instead of swallowing them silently.
+- Clarify scheduler wakeup trigger event data around `turn_id` while preserving backward compatibility.
+
+### Tests
+- Expand regression coverage for hooks, planner schema/loading, scheduler persistence, TUI reconnect/replay behavior, CLI bootstrap/system dependency commands, and memory archive errors.
+- Validate the full suite at 412 passing tests.
+
 ## [0.1.13] - 2026-05-07
 ### Changed
 - Reorganize built-in tools into a `codex_agent.builtin_tools` package with separate modules for file, shell, vision, system, and server-tool responsibilities.

{codex_agent_framework-0.1.13 → codex_agent_framework-0.1.15}/MANIFEST.in

@@ -3,5 +3,7 @@ include LICENSE
 include CHANGELOG.md
 recursive-include codex_agent/prompts *.txt
 include codex_agent/get_text/default_gitignore
+recursive-include codex_agent/scripts *.sh
+include dependencies.txt
 recursive-exclude * __pycache__
 recursive-exclude * *.py[co]

{codex_agent_framework-0.1.13/codex_agent_framework.egg-info → codex_agent_framework-0.1.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-agent-framework
-Version: 0.1.13
+Version: 0.1.15
 Summary: A lightweight event-driven Codex agent runtime.
 Author: Baptiste
 License-Expression: MIT
@@ -74,7 +74,9 @@ It provides a reusable `Agent` abstraction with persistent sessions, local tools
 - Python 3.10 or newer.
 - A working model backend configuration compatible with `codex-backend-sdk` / OpenAI usage.
 - GTK 3 plus Ayatana AppIndicator or AppIndicator bindings are needed for the tray controller on Linux.
-- Playwright's managed Chromium browser is used for rendered web extraction when static fetching is insufficient. Install it with `python -m playwright install chromium` if needed.
+- Desktop automation on Linux/X11 uses explicit system tools: `wmctrl`, `xdotool`, and `xclip`.
+- Playwright's managed Chromium browser is used for rendered web extraction when static fetching is insufficient.
+- See `dependencies.txt` for the full list of optional non-Python system dependencies.
 
 ## Installation
 
@@ -90,6 +92,26 @@ For development:
 python -m pip install -e '.[dev]'
 ```
 
+Install optional Linux system dependencies for browser, desktop, tray, service, terminal, and audio features:
+
+```bash
+codex-agent install-system-deps -- -y
+```
+
+Or bootstrap a local desktop setup by installing system dependencies and then installing/starting the user services:
+
+```bash
+codex-agent bootstrap -- -y
+```
+
+Useful bootstrap variants:
+
+```bash
+codex-agent bootstrap --no-system-deps
+codex-agent bootstrap --no-start-service -- -y
+codex-agent install-system-deps -- --dry-run --no-tray --no-audio
+```
+
 ## Quick start
 
 Run the local server plus terminal TUI:
@@ -101,19 +123,29 @@ codex-agent
 Run only the long-lived local server:
 
 ```bash
-codex-agent server
+codex-agent start server
 ```
 
 Connect a TUI to an already running server:
 
 ```bash
-codex-agent chat
+codex-agent open tui
 ```
 
 Start only the tray controller:
 
 ```bash
-codex-agent tray
+codex-agent start tray
+```
+
+Headless runtime examples:
+
+```bash
+codex-agent status --json
+codex-agent tools
+codex-agent config get input_token_limit
+codex-agent config set input_token_limit 128000
+codex-agent run "summarize this repository"
 ```
 
 Install the user services for the server and tray controller:
@@ -122,6 +154,8 @@ Install the user services for the server and tray controller:
 codex-agent install-service
 ```
 
+For a first-time Linux desktop setup, `codex-agent bootstrap -- -y` combines optional system dependency installation with service installation/startup. The command forwards arguments after `--` to the system dependency installer.
+
 Or use the agent from Python:
 
 ```python
@@ -235,6 +269,7 @@ Key endpoints:
 GET  /health
 GET  /status
 GET  /config
+PATCH /config
 GET  /session
 GET  /sessions
 GET  /messages
@@ -356,13 +391,15 @@ agent = Agent(
 )
 ```
 
-Configuration is persisted to `agent_config.json` in the runtime directory when updated through agent helpers or slash commands.
+Configuration is persisted to `agent_config.json` in the runtime directory when updated through agent helpers, slash commands, the HTTP API, or `codex-agent config set`.
 
 ## Project layout
 
 ```text
 codex_agent/                    Python package
 codex_agent/agent.py            Agent, AgentConfig, AgentSession
+codex_agent/agent_runtime.py    Runtime abstraction for server, CLI, and process adapters
+codex_agent/cli/                Command line interface package
 codex_agent/plugin.py           Stateful plugin base class
 codex_agent/builtin_tools/     Built-in local tools package
 codex_agent/builtin_commands.py Built-in slash commands
@@ -388,7 +425,7 @@ The tests isolate `AGENT_RUNTIME_DIR` automatically, so they should not create o
 Current baseline:
 
 ```text
-376 passed
+82 targeted release-regression tests passed
 ```
 
 ## Packaging
@@ -400,9 +437,11 @@ python -m pip install build
 python -m build
 ```
 
-The distribution includes prompt text files and `codex_agent/get_text/default_gitignore` through package data and `MANIFEST.in`.
+The distribution includes prompt text files, `codex_agent/get_text/default_gitignore`, and the packaged Linux system dependency installer through package data and `MANIFEST.in`.
 
 ## Recent changes
+- `0.1.15`: add the `AgentRuntime` interface for server/CLI/process adapters, split the CLI into a package with headless runtime commands, add `codex-agent config set` plus `PATCH /config`, and make built-in tools/providers/plugins configurable.
+- `0.1.14`: add HookManager infrastructure, planner/scheduler robustness fixes, documented system dependencies, `codex-agent install-system-deps`, `codex-agent bootstrap`, and improved TUI SSE reconnect/replay handling.
 - `0.1.13`: reorganize built-in tools into a `codex_agent.builtin_tools` package, keeping the public import surface compatible while separating file, shell, vision, system, and server-tool modules.
 - `0.1.12`: add a persistent Playwright/Chromium browser controller with tab navigation, DOM/action snapshots, screenshots, form/click/key tools, and `browser_goto(url)` for active-tab navigation.
 - `0.1.11`: split strict line-numbered UTF-8 `read` from unnumbered extracted `view`, preserve blank lines in read snippets, and show persistent+temporary message counts in the TUI status bar.

{codex_agent_framework-0.1.13 → codex_agent_framework-0.1.15}/README.md

@@ -25,7 +25,9 @@ It provides a reusable `Agent` abstraction with persistent sessions, local tools
 - Python 3.10 or newer.
 - A working model backend configuration compatible with `codex-backend-sdk` / OpenAI usage.
 - GTK 3 plus Ayatana AppIndicator or AppIndicator bindings are needed for the tray controller on Linux.
-- Playwright's managed Chromium browser is used for rendered web extraction when static fetching is insufficient. Install it with `python -m playwright install chromium` if needed.
+- Desktop automation on Linux/X11 uses explicit system tools: `wmctrl`, `xdotool`, and `xclip`.
+- Playwright's managed Chromium browser is used for rendered web extraction when static fetching is insufficient.
+- See `dependencies.txt` for the full list of optional non-Python system dependencies.
 
 ## Installation
 
@@ -41,6 +43,26 @@ For development:
 python -m pip install -e '.[dev]'
 ```
 
+Install optional Linux system dependencies for browser, desktop, tray, service, terminal, and audio features:
+
+```bash
+codex-agent install-system-deps -- -y
+```
+
+Or bootstrap a local desktop setup by installing system dependencies and then installing/starting the user services:
+
+```bash
+codex-agent bootstrap -- -y
+```
+
+Useful bootstrap variants:
+
+```bash
+codex-agent bootstrap --no-system-deps
+codex-agent bootstrap --no-start-service -- -y
+codex-agent install-system-deps -- --dry-run --no-tray --no-audio
+```
+
 ## Quick start
 
 Run the local server plus terminal TUI:
@@ -52,19 +74,29 @@ codex-agent
 Run only the long-lived local server:
 
 ```bash
-codex-agent server
+codex-agent start server
 ```
 
 Connect a TUI to an already running server:
 
 ```bash
-codex-agent chat
+codex-agent open tui
 ```
 
 Start only the tray controller:
 
 ```bash
-codex-agent tray
+codex-agent start tray
+```
+
+Headless runtime examples:
+
+```bash
+codex-agent status --json
+codex-agent tools
+codex-agent config get input_token_limit
+codex-agent config set input_token_limit 128000
+codex-agent run "summarize this repository"
 ```
 
 Install the user services for the server and tray controller:
@@ -73,6 +105,8 @@ Install the user services for the server and tray controller:
 codex-agent install-service
 ```
 
+For a first-time Linux desktop setup, `codex-agent bootstrap -- -y` combines optional system dependency installation with service installation/startup. The command forwards arguments after `--` to the system dependency installer.
+
 Or use the agent from Python:
 
 ```python
@@ -186,6 +220,7 @@ Key endpoints:
 GET  /health
 GET  /status
 GET  /config
+PATCH /config
 GET  /session
 GET  /sessions
 GET  /messages
@@ -307,13 +342,15 @@ agent = Agent(
 )
 ```
 
-Configuration is persisted to `agent_config.json` in the runtime directory when updated through agent helpers or slash commands.
+Configuration is persisted to `agent_config.json` in the runtime directory when updated through agent helpers, slash commands, the HTTP API, or `codex-agent config set`.
 
 ## Project layout
 
 ```text
 codex_agent/                    Python package
 codex_agent/agent.py            Agent, AgentConfig, AgentSession
+codex_agent/agent_runtime.py    Runtime abstraction for server, CLI, and process adapters
+codex_agent/cli/                Command line interface package
 codex_agent/plugin.py           Stateful plugin base class
 codex_agent/builtin_tools/     Built-in local tools package
 codex_agent/builtin_commands.py Built-in slash commands
@@ -339,7 +376,7 @@ The tests isolate `AGENT_RUNTIME_DIR` automatically, so they should not create o
 Current baseline:
 
 ```text
-376 passed
+82 targeted release-regression tests passed
 ```
 
 ## Packaging
@@ -351,9 +388,11 @@ python -m pip install build
 python -m build
 ```
 
-The distribution includes prompt text files and `codex_agent/get_text/default_gitignore` through package data and `MANIFEST.in`.
+The distribution includes prompt text files, `codex_agent/get_text/default_gitignore`, and the packaged Linux system dependency installer through package data and `MANIFEST.in`.
 
 ## Recent changes
+- `0.1.15`: add the `AgentRuntime` interface for server/CLI/process adapters, split the CLI into a package with headless runtime commands, add `codex-agent config set` plus `PATCH /config`, and make built-in tools/providers/plugins configurable.
+- `0.1.14`: add HookManager infrastructure, planner/scheduler robustness fixes, documented system dependencies, `codex-agent install-system-deps`, `codex-agent bootstrap`, and improved TUI SSE reconnect/replay handling.
 - `0.1.13`: reorganize built-in tools into a `codex_agent.builtin_tools` package, keeping the public import surface compatible while separating file, shell, vision, system, and server-tool modules.
 - `0.1.12`: add a persistent Playwright/Chromium browser controller with tab navigation, DOM/action snapshots, screenshots, form/click/key tools, and `browser_goto(url)` for active-tab navigation.
 - `0.1.11`: split strict line-numbered UTF-8 `read` from unnumbered extracted `view`, preserve blank lines in read snippets, and show persistent+temporary message counts in the TUI status bar.

{codex_agent_framework-0.1.13 → codex_agent_framework-0.1.15}/codex_agent/__init__.py

@@ -37,6 +37,7 @@ from .message import (
     AssistantMessage,
     CompactionMessage,
     DeveloperMessage,
+    InterruptMessage,
     Message,
     MessageChunk,
     ProviderMessage,
@@ -98,6 +99,7 @@ __all__ = [
     "AssistantMessage",
     "CompactionMessage",
     "DeveloperMessage",
+    "InterruptMessage",
     "Message",
     "MessageChunk",
     "ProviderMessage",

codex_agent_framework-0.1.15/codex_agent/__main__.py

@@ -0,0 +1,7 @@
+"""Compatibility entrypoint for ``python -m codex_agent``."""
+
+from .cli.main import main
+
+
+if __name__ == '__main__':
+    main()

{codex_agent_framework-0.1.13 → codex_agent_framework-0.1.15}/codex_agent/agent.py

@@ -7,6 +7,7 @@ from .image import ImageMessage
 from .command import CommandManager
 from .config import ConfigManager
 from .context import ContextManager
+from .hooks import HookManager
 from .mainloop import MainLoopManager
 from .plugin import PluginsManager
 from .registry import RegistryManager
@@ -14,7 +15,7 @@ from .runtime import RuntimeManager
 from .sessions import SessionsManager
 from .status import StatusManager
 from .tool import ImageGenerationTool, reset_current_agent, set_current_agent
-from .ai import AIClient
+from .ai import AIBadRequestError, AIClient
 from .voice import VoiceProcessor
 from .latex import LaTeXProcessor
 from .event import AgentInterruptRequestedEvent, AgentInterrupted, AgentInterruptedEvent, AudioPlaybackEvent, EventBus
@@ -49,7 +50,7 @@ class Agent:
         self.plugins=self.plugins_manager.plugins
         self.sessions_manager=SessionsManager(self)
         self.runtime=RuntimeManager(self)
-        self.hooks=modict()
+        self.hooks=HookManager(self)
         self.on(AudioPlaybackEvent, self.handle_audio_playback)
         self.mainloop_manager=MainLoopManager(self)
         self._interrupt_requested=ThreadEvent()
@@ -126,7 +127,7 @@ class Agent:
             self.emit(AgentInterruptedEvent, reason=reason)
         self.emit(AgentInterruptRequestedEvent, reason=reason, interrupted=True, error=str(abort_error) if abort_error else "")
         return True
-    
+
     def clear_interrupt(self):
         self._interrupt_requested.clear()
 
@@ -189,7 +190,6 @@ class Agent:
         if self.mainloop_manager.dumping_pending:
             return self.sessions_manager.append_message(msg)
         return self.mainloop_manager.add_pending_message(msg)
-    
 
     def new_message(self,pending=False,**kwargs):
         """Helper to create and add a message based on provided keyword arguments.
@@ -203,7 +203,7 @@ class Agent:
         """
         msg=message_from_data(kwargs)
         return self.add_message(msg,pending=pending)
-    
+
     def add_image(self,source,pending=False,**kwargs):
         if source:
             img=ImageMessage(
@@ -247,21 +247,24 @@ class Agent:
         if hasattr(self, "mainloop_manager") and self.mainloop_manager.should_queue_state_command():
             return self.submit("add_hook", key=key, func=func).wait()
 
-        self.hooks.setdefault(key, []).append(func)
-        return func
+        return self.hooks.add(key, func)
 
     def has_hook(self, key):
-        return bool(self.hooks.get(key))
+        return self.hooks.has(key)
+
+    def run_hook(self, key, **payload):
+        agent_context = set_current_agent(self)
+        try:
+            return self.hooks.run(key, **payload)
+        finally:
+            reset_current_agent(agent_context)
 
     def run_hooks(self, key, *args):
-        results = []
-        for hook in list(self.hooks.get(key, ())):
-            agent_context = set_current_agent(self)
-            try:
-                results.append(hook(*args))
-            finally:
-                reset_current_agent(agent_context)
-        return results
+        agent_context = set_current_agent(self)
+        try:
+            return self.hooks.run_legacy(key, *args)
+        finally:
+            reset_current_agent(agent_context)
 
     def get_messages(self,filter=None):
         return self.sessions_manager.messages(filter=filter)
@@ -321,16 +324,21 @@ class Agent:
             )
             messages = self.context_manager.get_context()
 
-        message=self.ai.run(
-            messages=messages,
-            tools=self.registry.get_response_tools(),
-            prompt_cache_key=self.current_session_id,
-            **self.config.extract('model','reasoning_effort','verbosity','parallel_tool_calls')
-        )
+        try:
+            message=self.ai.run(
+                messages=messages,
+                tools=self.registry.get_response_tools(),
+                prompt_cache_key=self.current_session_id,
+                **self.config.extract('model','reasoning_effort','verbosity','parallel_tool_calls')
+            )
+        except AIBadRequestError:
+            self.sessions_manager.restore_api_success_backup()
+            raise
         self.sessions_manager.append_message(message)
         for item in message.output_items:
             if self.registry.server_tool_for_item(item):
                 self.sessions_manager.append_message(ServerToolResponseMessage(item=item))
+        self.sessions_manager.save_api_success_backup()
         return message
 
     def speak(self,text,**kwargs):
@@ -381,7 +389,7 @@ class Agent:
         """
         if source is None:
             raise ValueError("An audio source must be provided")
-        
+
         # Transcribe audio to text
         transcribed_text = self.ai.audio_to_text(
             source=source,

{codex_agent_framework-0.1.13 → codex_agent_framework-0.1.15}/codex_agent/agent_runtime.py

@@ -3,12 +3,13 @@ import multiprocessing
 import queue
 import threading
 import uuid
+from abc import ABC, abstractmethod
 
 from modict import modict
 
 from .agent import Agent
 from .event import Event
-from .message import message_from_data
+from .message import UserMessage, message_from_data
 
 
 def jsonable(value):
@@ -19,7 +20,143 @@ class AgentRuntimeError(RuntimeError):
     pass
 
 
-class InProcessAgentRuntime:
+class AgentRuntime(ABC):
+    """Canonical contract for exposing an agent to external applications.
+
+    This ABC is the source of truth for every public surface that drives or
+    introspects an Agent from outside the core object: HTTP server, headless CLI,
+    local process adapters, remote clients and future integrations should all
+    implement or target this runtime interface instead of depending on Agent
+    internals directly.
+    """
+
+    @abstractmethod
+    def start(self):
+        return self
+
+    @abstractmethod
+    def stop(self, timeout=None):
+        return self
+
+    @abstractmethod
+    def on_event(self, handler):
+        return handler
+
+    @property
+    @abstractmethod
+    def busy(self):
+        return False
+
+    @property
+    @abstractmethod
+    def current_turn_id(self):
+        return None
+
+    @property
+    @abstractmethod
+    def current_session_id(self):
+        return None
+
+    @abstractmethod
+    def get_status(self):
+        raise NotImplementedError
+
+    @abstractmethod
+    def config(self):
+        raise NotImplementedError
+
+    @abstractmethod
+    def update_config(self, values=None, save=True, **kwargs):
+        raise NotImplementedError
+
+    @abstractmethod
+    def session(self):
+        raise NotImplementedError
+
+    @abstractmethod
+    def sessions(self):
+        raise NotImplementedError
+
+    @abstractmethod
+    def messages(self):
+        raise NotImplementedError
+
+    @abstractmethod
+    def memory(self):
+        raise NotImplementedError
+
+    @abstractmethod
+    def tools(self):
+        raise NotImplementedError
+
+    @abstractmethod
+    def wakeups(self, include_done=True):
+        raise NotImplementedError
+
+    @abstractmethod
+    def start_new_session(self):
+        raise NotImplementedError
+
+    @abstractmethod
+    def load_session(self, session_id):
+        raise NotImplementedError
+
+    @abstractmethod
+    def delete_session(self, session_id):
+        raise NotImplementedError
+
+    @abstractmethod
+    def navigate_session(self, direction):
+        raise NotImplementedError
+
+    @abstractmethod
+    def interrupt(self, reason="api"):
+        raise NotImplementedError
+
+    @abstractmethod
+    def start_turn(self):
+        raise NotImplementedError
+
+    @abstractmethod
+    def submit_command(self, prompt):
+        raise NotImplementedError
+
+    @abstractmethod
+    def submit_message(self, message):
+        raise NotImplementedError
+
+    def submit_prompt(self, prompt):
+        if not prompt or not str(prompt).strip():
+            raise ValueError("prompt must not be empty")
+        if str(prompt).strip().startswith("/"):
+            if self.busy:
+                raise RuntimeError("agent is busy")
+            turn_id = self.submit_command(prompt)
+            if turn_id is None:
+                raise RuntimeError("agent is busy")
+            return modict(command=True, queued=False, turn_id=turn_id)
+        was_busy = self.busy
+        result = self.submit_message(UserMessage(content=prompt))
+        return modict(
+            queued=was_busy,
+            pending_message_id=result.message.id,
+            turn_id=result.get("turn_id") or self.current_turn_id,
+        )
+
+    @abstractmethod
+    def schedule_wakeup(self, **kwargs):
+        raise NotImplementedError
+
+    @abstractmethod
+    def cancel_wakeup(self, job_id):
+        raise NotImplementedError
+
+    @abstractmethod
+    def delete_wakeup(self, job_id):
+        raise NotImplementedError
+
+
+class InProcessAgentRuntime(AgentRuntime):
     def __init__(self, agent: Agent):
         self.agent = agent
 
@@ -53,6 +190,9 @@ class InProcessAgentRuntime:
     def config(self):
         return self.agent.config
 
+    def update_config(self, values=None, save=True, **kwargs):
+        return self.agent.config_manager.update(values, save=save, **kwargs)
+
     def session(self):
         return self.agent.session
 
@@ -115,7 +255,7 @@ class InProcessAgentRuntime:
         return job
 
 
-class ProcessAgentRuntime:
+class ProcessAgentRuntime(AgentRuntime):
     def __init__(self, agent_kwargs=None, *, command_timeout=5.0, status_timeout=0.5):
         self.agent_kwargs = dict(agent_kwargs or {})
         self.command_timeout = float(command_timeout)
@@ -294,6 +434,13 @@ class ProcessAgentRuntime:
     def config(self):
         return self._cached_call("config")
 
+    def update_config(self, values=None, save=True, **kwargs):
+        payload = dict(values or {})
+        payload.update(kwargs)
+        result = self.call("update_config", {"values": payload, "save": save}, timeout=self.command_timeout)
+        self.cache.config = result
+        return result
+
     def session(self):
         return self._cached_call("session")
 
@@ -452,6 +599,8 @@ def run_worker_command(agent, name, payload):
         return status
     if name == "config":
         return agent.config
+    if name == "update_config":
+        return agent.config_manager.update(payload.get("values") or {}, save=payload.get("save", True))
     if name == "session":
         return agent.session
     if name == "sessions":