codex-agent-framework 0.1.12__tar.gz → 0.1.14__tar.gz

{codex_agent_framework-0.1.12 → codex_agent_framework-0.1.14}/CHANGELOG.md

@@ -4,6 +4,34 @@ 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.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.
+- Keep the public `codex_agent.builtin_tools` import surface compatible by re-exporting the existing built-in tools and helpers from the package initializer.
+
+### Tests
+- Update built-in tool regression coverage for the package layout and validate the full suite at 376 passing tests.
+
 ## [0.1.12] - 2026-05-05
 ### Added
 - Add a persistent Playwright/Chromium browser controller with tools to open/close the browser, select tabs, navigate, click, fill, select options, press keys, inspect action snapshots, and capture screenshots.

{codex_agent_framework-0.1.12 → codex_agent_framework-0.1.14}/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.12/codex_agent_framework.egg-info → codex_agent_framework-0.1.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-agent-framework
-Version: 0.1.12
+Version: 0.1.14
 Summary: A lightweight event-driven Codex agent runtime.
 Author: Baptiste
 License-Expression: MIT
@@ -21,6 +21,7 @@ Requires-Dist: codex-backend-sdk
 Requires-Dist: fastapi
 Requires-Dist: filetype
 Requires-Dist: modict
+Requires-Dist: mss
 Requires-Dist: numpy
 Requires-Dist: odfpy
 Requires-Dist: openai
@@ -31,6 +32,7 @@ Requires-Dist: playwright
 Requires-Dist: pydub
 Requires-Dist: pypdf
 Requires-Dist: pynteract
+Requires-Dist: pywinctl
 Requires-Dist: python-docx
 Requires-Dist: PyYAML
 Requires-Dist: regex
@@ -72,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
 
@@ -88,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:
@@ -120,6 +144,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
@@ -361,9 +387,11 @@ Configuration is persisted to `agent_config.json` in the runtime directory when
 ```text
 codex_agent/                    Python package
 codex_agent/agent.py            Agent, AgentConfig, AgentSession
-codex_agent/builtin_tools.py    Built-in local tools
+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
 codex_agent/builtin_providers.py Built-in context providers
+codex_agent/builtin_plugins/    Auto-loaded stateful plugin packages
 codex_agent/prompts/            Packaged prompt templates
 codex_agent/get_text/           Document extraction helpers
 tests/                          Test suite
@@ -384,7 +412,7 @@ The tests isolate `AGENT_RUNTIME_DIR` automatically, so they should not create o
 Current baseline:
 
 ```text
-293 passed
+412 passed
 ```
 
 ## Packaging
@@ -396,9 +424,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.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.
 - `0.1.10`: persist only backend compaction summaries, drop bulky compacted conversation payloads, and refresh context status after compaction.

{codex_agent_framework-0.1.12 → codex_agent_framework-0.1.14}/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:
@@ -73,6 +95,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
@@ -314,9 +338,11 @@ Configuration is persisted to `agent_config.json` in the runtime directory when
 ```text
 codex_agent/                    Python package
 codex_agent/agent.py            Agent, AgentConfig, AgentSession
-codex_agent/builtin_tools.py    Built-in local tools
+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
 codex_agent/builtin_providers.py Built-in context providers
+codex_agent/builtin_plugins/    Auto-loaded stateful plugin packages
 codex_agent/prompts/            Packaged prompt templates
 codex_agent/get_text/           Document extraction helpers
 tests/                          Test suite
@@ -337,7 +363,7 @@ The tests isolate `AGENT_RUNTIME_DIR` automatically, so they should not create o
 Current baseline:
 
 ```text
-293 passed
+412 passed
 ```
 
 ## Packaging
@@ -349,9 +375,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.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.
 - `0.1.10`: persist only backend compaction summaries, drop bulky compacted conversation payloads, and refresh context status after compaction.

codex_agent_framework-0.1.14/codex_agent/__init__.py

@@ -0,0 +1,138 @@
+from .agent import Agent
+from .client import AgentClient
+from .config import AgentConfig, ConfigManager, DEFAULT_SYSTEM_PROMPT
+from .context import ContextManager
+from .event import (
+    AgentInterruptRequestedEvent,
+    AgentInterrupted,
+    AgentInterruptedEvent,
+    AgentTurnEndEvent,
+    AgentTurnErrorEvent,
+    AgentTurnStartEvent,
+    AssistantStepEndEvent,
+    AssistantStepStartEvent,
+    AssistantTurnEndEvent,
+    AssistantTurnStartEvent,
+    AudioPlaybackEvent,
+    CompactionCompletedEvent,
+    CompactionRequestedEvent,
+    Event,
+    EventBus,
+    MessageAddedEvent,
+    MessageSubmittedEvent,
+    ResponseContentDeltaEvent,
+    ResponseDoneEvent,
+    ResponseMessageDeltaEvent,
+    ResponseOutputItemEvent,
+    ResponseReasoningDeltaEvent,
+    ResponseStartEvent,
+    ResponseToolCallsDeltaEvent,
+    ServerToolCallEvent,
+    SessionDeletedEvent,
+    SessionLoadedEvent,
+    ToolCallDoneEvent,
+    ToolCallStartEvent,
+)
+from .message import (
+    AssistantMessage,
+    CompactionMessage,
+    DeveloperMessage,
+    InterruptMessage,
+    Message,
+    MessageChunk,
+    ProviderMessage,
+    ServerToolResponseMessage,
+    SystemMessage,
+    ToolResultMessage,
+    ToolResultWrapper,
+    UserMessage,
+)
+from .image import ImageMessage
+from .mainloop import MainLoopManager
+from .memory import MemoryEntry, RAGMemory, RAGMemoryConfig
+from .plugin import Plugin, PluginsManager
+from .registry import RegistryManager
+from .command import AgentCommand, AgentFuture, CommandManager, command
+from .provider import provider
+from .runtime import RuntimeManager
+from .sessions import AgentSession, SessionsManager
+from .status import StatusManager
+from .tool import ImageGenerationTool, ServerTool, Tool, WebSearchTool, get_agent, get_current_call_id, tool
+from .worker import SummarizerWorker, TurnSummaryWorker, Worker
+
+__all__ = [
+    "Agent",
+    "AgentClient",
+    "AgentConfig",
+    "ConfigManager",
+    "DEFAULT_SYSTEM_PROMPT",
+    "ContextManager",
+    "AgentInterruptRequestedEvent",
+    "AgentInterrupted",
+    "AgentInterruptedEvent",
+    "AgentTurnEndEvent",
+    "AgentTurnErrorEvent",
+    "AgentTurnStartEvent",
+    "AssistantStepEndEvent",
+    "AssistantStepStartEvent",
+    "AssistantTurnEndEvent",
+    "AssistantTurnStartEvent",
+    "AudioPlaybackEvent",
+    "CompactionCompletedEvent",
+    "CompactionRequestedEvent",
+    "Event",
+    "EventBus",
+    "MessageAddedEvent",
+    "MessageSubmittedEvent",
+    "ResponseContentDeltaEvent",
+    "ResponseDoneEvent",
+    "ResponseMessageDeltaEvent",
+    "ResponseOutputItemEvent",
+    "ResponseReasoningDeltaEvent",
+    "ResponseStartEvent",
+    "ResponseToolCallsDeltaEvent",
+    "ServerToolCallEvent",
+    "SessionDeletedEvent",
+    "SessionLoadedEvent",
+    "ToolCallDoneEvent",
+    "ToolCallStartEvent",
+    "AssistantMessage",
+    "CompactionMessage",
+    "DeveloperMessage",
+    "InterruptMessage",
+    "Message",
+    "MessageChunk",
+    "ProviderMessage",
+    "ServerToolResponseMessage",
+    "SystemMessage",
+    "ToolResultMessage",
+    "ToolResultWrapper",
+    "UserMessage",
+    "ImageMessage",
+    "MainLoopManager",
+    "MemoryEntry",
+    "RAGMemory",
+    "RAGMemoryConfig",
+    "Plugin",
+    "PluginsManager",
+    "RegistryManager",
+    "AgentCommand",
+    "AgentFuture",
+    "CommandManager",
+    "command",
+    "provider",
+    "RuntimeManager",
+    "AgentSession",
+    "SessionsManager",
+    "StatusManager",
+    "ImageGenerationTool",
+    "ServerTool",
+    "Tool",
+    "WebSearchTool",
+    "get_agent",
+    "get_current_call_id",
+    "tool",
+    "SummarizerWorker",
+    "TurnSummaryWorker",
+    "Worker",
+]

{codex_agent_framework-0.1.12 → codex_agent_framework-0.1.14}/codex_agent/__main__.py

@@ -1,4 +1,5 @@
 from pathlib import Path
+import subprocess
 
 from . import Agent
 from .chat import Chat
@@ -26,8 +27,7 @@ def default_agent():
 
 
 def configure_server_url(agent, host, port):
-    if hasattr(agent, "update_config"):
-        agent.update_config(server_url=f"http://{host}:{port}", save=False)
+    agent.config_manager.update(server_url=f"http://{host}:{port}", save=False)
     return agent
 
 
@@ -48,6 +48,33 @@ def run_tray_mode(base_url="http://127.0.0.1:8765"):
     run_tray(base_url=base_url)
 
 
+def run_system_deps_installer(extra_args=None):
+    script = Path(__file__).parent / "scripts" / "install-system-dependencies.sh"
+    if not script.is_file():
+        raise RuntimeError(f"System dependency installer not found: {script}")
+    return subprocess.call([str(script), *(extra_args or [])])
+
+
+def run_bootstrap(
+    host="127.0.0.1",
+    port=8765,
+    *,
+    system_deps_args=None,
+    install_system_deps=True,
+    install_service=True,
+    start_service=True,
+):
+    if install_system_deps:
+        code = run_system_deps_installer(system_deps_args or [])
+        if code:
+            return code
+    if install_service:
+        path = install_user_service(host=host, port=port, enable=True, start=start_service)
+        action = "Installed and started" if start_service else "Installed"
+        print(f"{action} user services: {path}")
+    return 0
+
+
 def run_local(host="127.0.0.1", port=8765):
     import threading
     import time
@@ -78,14 +105,19 @@ def main(argv=None):
     parser.add_argument(
         "mode",
         nargs="?",
-        choices=["local", "server", "chat", "tray", "install-service", "uninstall-service"],
+        choices=["local", "server", "chat", "tray", "install-service", "uninstall-service", "install-system-deps", "bootstrap"],
         default="local",
-        help="local starts an embedded server then the TUI client; server runs only the API; chat connects to an existing API; tray starts the desktop tray controller; install-service installs a user systemd service.",
+        help="local starts an embedded server then the TUI client; server runs only the API; chat connects to an existing API; tray starts the desktop tray controller; install-service installs a user systemd service; install-system-deps installs optional OS packages; bootstrap installs system deps then user services.",
     )
     parser.add_argument("--host", default="127.0.0.1")
     parser.add_argument("--port", type=int, default=8765)
     parser.add_argument("--url", default=None, help="Base URL for chat mode, e.g. http://127.0.0.1:8765")
-    args = parser.parse_args(argv)
+    parser.add_argument("--no-system-deps", action="store_true", help="With bootstrap, skip OS dependency installation.")
+    parser.add_argument("--no-service", action="store_true", help="With bootstrap, skip user service installation.")
+    parser.add_argument("--no-start-service", action="store_true", help="With bootstrap, install services but do not start them.")
+    args, extra_args = parser.parse_known_args(argv)
+    if args.mode not in {"install-system-deps", "bootstrap"} and extra_args:
+        parser.error(f"unrecognized arguments: {' '.join(extra_args)}")
 
     if args.mode == "server":
         run_server(args.host, args.port)
@@ -99,6 +131,23 @@ def main(argv=None):
     elif args.mode == "uninstall-service":
         path = uninstall_user_service(disable=True, stop=True)
         print(f"Uninstalled user service: {path}")
+    elif args.mode == "install-system-deps":
+        installer_args = extra_args
+        if installer_args and installer_args[0] == "--":
+            installer_args = installer_args[1:]
+        raise SystemExit(run_system_deps_installer(installer_args))
+    elif args.mode == "bootstrap":
+        installer_args = extra_args
+        if installer_args and installer_args[0] == "--":
+            installer_args = installer_args[1:]
+        raise SystemExit(run_bootstrap(
+            host=args.host,
+            port=args.port,
+            system_deps_args=installer_args,
+            install_system_deps=not args.no_system_deps,
+            install_service=not args.no_service,
+            start_service=not args.no_start_service,
+        ))
     else:
         run_local(args.host, args.port)