codex-agent-framework 0.1.6__tar.gz → 0.1.9__tar.gz

codex_agent_framework-0.1.9/CHANGELOG.md

@@ -0,0 +1,114 @@
+# Changelog
+
+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.9] - 2026-05-05
+### Changed
+- Maintenance release for the packaged distribution after validating the updated local execution environment and deploy workflow.
+
+## [0.1.8] - 2026-05-05
+### Changed
+- Scope TUI startup replay and SSE catch-up events to the current session so reopening the UI after session navigation cannot replay turns from another session.
+- Make the agent process normalize its execution environment from `sys.executable`, putting the project interpreter first on `PATH` and exposing `PYTHON` / `PYTHON_EXECUTABLE`.
+- Generate systemd and launchd service definitions with the project Python environment propagated explicitly to server and tray processes.
+
+### Fixed
+- Ensure the agent `bash` tool resolves `python` and `pytest` from the environment where `codex-agent-framework` is installed, even when launched by a minimal service manager environment.
+- Preserve direct `agent.tools.<name>(...)` calls by binding registered tools back to their owning agent for runtime context lookup.
+
+### Tests
+- Add regression coverage for session-scoped replay, same-session SSE catch-up filtering, service environment generation, and bash tool Python resolution.
+
+## [0.1.7] - 2026-05-05
+### Added
+- Add durable RAG memory backed by `memory.json`, with memory entries modeled as developer messages and retrieved by semantic similarity plus optional recency scoring.
+- Add memory tools for creating, editing, deleting, and searching entries, with XML-formatted search output.
+- Add automatic fire-and-forget turn summarization into memory after completed agent turns.
+- Add scheduled wakeups backed by `wakeups.json`, including one-shot and periodic wakeups plus server restart wakeup recovery.
+- Add a desktop tray controller, user service install/uninstall helpers, and agent tools/endpoints to open or close the TUI.
+- Add `/status`, `/wakeups`, `/tui`, `/events/replay`, and related server endpoints for a purely client-driven TUI.
+- Add compact UI status data for context usage, message ratio, WHAM quota percentages, and current model.
+
+### Changed
+- Run the long-lived agent in a separate worker process behind the FastAPI bridge so the server remains responsive while the agent is busy.
+- Make the Textual TUI robust to server restarts and reconnects by replaying the latest turn, tracking SSE event sequence cursors, and allowing same-client SSE replacement.
+- Remove SSE read timeouts for the event stream while keeping immediate reconnect attempts after connection loss.
+- Improve token counting by making messages responsible for cached API token estimates and including tool specs in context estimates.
+- Treat leading system messages as Responses API instructions rather than ordinary history messages.
+- Remove the legacy Streamlit dependency and replace `PyPDF2` with `pypdf`.
+
+### Fixed
+- Prevent stale SSE subscribers from blocking a reconnecting TUI with a false second-client error.
+- Prevent local TUI handler errors from being displayed as server disconnects.
+- Truncate long embedding inputs to avoid backend embedding context length errors.
+- Add `audioop-lts` for Python 3.13+ compatibility with `pydub`.
+
+### Tests
+- Expand coverage for memory, token estimates, server replay, SSE reconnects, process runtime shutdown, tray/service helpers, scheduler wakeups, and TUI status behavior.
+
+## [0.1.6] - 2026-05-04
+### Added
+- Add an async-style agent mainloop with command futures so turns and state mutations can be coordinated through one runtime.
+- Add a FastAPI REST/SSE bridge and an `AgentClient` HTTP/SSE client for decoupled interfaces.
+- Add CLI modes for local embedded server + TUI client, server-only, and client-only chat operation.
+
+### Changed
+- Decouple the Textual chat UI from direct `Agent` access; the TUI now communicates with the server through HTTP and SSE.
+- Stream lightweight response deltas instead of cumulative content, reducing SSE traffic and client backpressure.
+- Use unbounded subscriber queues with ping events for more reliable SSE client delivery.
+
+### Tests
+- Add coverage for the server bridge, HTTP/SSE client, async runtime behavior, CLI modes, and event lifecycle.
+
+## [0.1.5] - 2026-05-03
+### Changed
+- Refine the default Textual chat UI with a pure black background, black multiline input area, subtler scrollbars, a smaller step-end marker, and English UI labels.
+
+
+## [0.1.4] - 2026-05-03
+### Added
+- Make the Textual REPL UI the default chat interface, with multiline input, subdued colors, visual speaker separators, step-end markers, and cleaner tool-call rendering.
+- Add assistant turn and assistant step lifecycle events for UI and runtime integrations.
+- Add a `/voice` command to show, toggle, or select the configured voice mode.
+
+### Changed
+- Remove the legacy prompt-toolkit chat UI and the temporary `--textual` CLI flag.
+
+### Tests
+- Add CLI coverage for starting the default chat UI and update chat status formatting tests.
+
+
+## [0.1.3] - 2026-05-03
+### Added
+- Send the current session id as `prompt_cache_key` to the Codex backend, enabling server-side prompt cache reuse across calls from the same session.
+
+### Tests
+- Add regression coverage for prompt cache key propagation through agent response calls and Codex stream parameters.
+
+
+## [0.1.2] - 2026-05-03
+### Added
+- Add a `/clear` terminal chat command that clears the screen without touching session history.
+
+### Tests
+- Add regression coverage ensuring terminal screen clearing does not append session messages.
+
+
+## [0.1.1] - 2026-05-03
+### Fixed
+- Validate `ImageMessage` content before adding it to session state.
+- Prevent invalid or inaccessible observed images from polluting a session and breaking later SDK calls.
+
+### Tests
+- Add regression coverage for valid and invalid `ImageMessage` validation.
+- Verify `Agent.add_image()` rejects invalid images without appending a broken session message.
+
+
+## [0.1.0] - 2026-05-03
+
+### Added
+
+- Initial package metadata and console entry point.
+- Event-driven agent runtime, session persistence, tools, providers, commands, voice, image, and document extraction modules.
+- Test suite for core agent behavior, events, messages, image messages, utilities, and workers.

{codex_agent_framework-0.1.6/codex_agent_framework.egg-info → codex_agent_framework-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-agent-framework
-Version: 0.1.6
+Version: 0.1.9
 Summary: A lightweight event-driven Codex agent runtime.
 Author: Baptiste
 License-Expression: MIT
@@ -15,6 +15,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: audioop-lts; python_version >= "3.13"
 Requires-Dist: beautifulsoup4
 Requires-Dist: codex-backend-sdk
 Requires-Dist: fastapi
@@ -28,7 +29,7 @@ Requires-Dist: openpyxl
 Requires-Dist: pathspec
 Requires-Dist: pillow
 Requires-Dist: pydub
-Requires-Dist: PyPDF2
+Requires-Dist: pypdf
 Requires-Dist: pynteract
 Requires-Dist: python-docx
 Requires-Dist: PyYAML
@@ -43,8 +44,6 @@ Requires-Dist: uvicorn
 Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
-Provides-Extra: streamlit
-Requires-Dist: streamlit; extra == "streamlit"
 Dynamic: license-file
 
 # codex-agent
@@ -57,19 +56,23 @@ It provides a reusable `Agent` abstraction with persistent sessions, local tools
 
 ## Highlights
 
-- Interactive terminal agent exposed as `codex-agent`.
+- Local FastAPI agent server with a terminal TUI client and GTK tray controller.
+- Process-isolated agent runtime so the local server stays responsive while the agent works.
 - Persistent JSON sessions with `latest`, explicit session IDs, and session navigation commands.
+- Durable RAG memory backed by runtime JSON, with semantic search and automatic turn summaries.
+- Scheduled wakeups for one-shot or periodic autonomous agent turns.
 - Built-in local tools for reading, writing, editing, showing, observing, Bash, and Python execution.
 - Extensible tool, command, and provider decorators.
 - Event-driven internals for UI, streaming, voice, and automation integrations.
 - Document extraction helpers for folders, text files, URLs, PDFs, DOCX, XLSX, ODT, HTML, and more.
-- Optional image generation, image observation, voice, LaTeX, and Streamlit-oriented integration points.
+- Optional image generation, image observation, voice, and LaTeX integration points.
 - Packaged prompt assets and runtime defaults.
 
 ## Requirements
 
 - 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.
 - Firefox / GeckoDriver may be needed for Selenium-backed web extraction paths.
 
 ## Installation
@@ -86,18 +89,36 @@ For development:
 python -m pip install -e '.[dev]'
 ```
 
-Optional Streamlit support:
+## Quick start
+
+Run the local server plus terminal TUI:
 
 ```bash
-python -m pip install -e '.[streamlit]'
+codex-agent
 ```
 
-## Quick start
+Run only the long-lived local server:
+
+```bash
+codex-agent server
+```
 
-Run the bundled terminal assistant:
+Connect a TUI to an already running server:
 
 ```bash
-codex-agent
+codex-agent chat
+```
+
+Start only the tray controller:
+
+```bash
+codex-agent tray
+```
+
+Install the user services for the server and tray controller:
+
+```bash
+codex-agent install-service
 ```
 
 Or use the agent from Python:
@@ -140,6 +161,9 @@ tools/         user runtime tools
 providers/     user runtime context providers
 commands/      user runtime slash commands
 images/        generated or persisted image outputs
+memory.json    durable RAG memory entries
+wakeups.json   scheduled autonomous wakeups
+tui.json       currently registered TUI client process
 ```
 
 You can override the runtime location with:
@@ -194,9 +218,41 @@ The default agent registers local tools that can be exposed to the model:
 | `bash` | Execute shell commands. |
 | `observe` | Load an image into the conversation for visual analysis. |
 | `show` | Open a file, folder, or URL with the system default app/browser. |
+| `memory_add` / `memory_edit` / `memory_delete` / `memory_search` | Manage durable semantic memory entries. |
+| `schedule_wakeup` / `cancel_wakeup` / `list_wakeups` | Manage automatic future turns. |
+| `open_tui` / `close_tui` | Open or close the local TUI through the running server. |
 
 Use these with care: Bash, Python, write, and edit run with the current user's privileges.
 
+## Local server, TUI, and tray
+
+The server exposes the agent through a thin FastAPI bridge. Its REST and SSE endpoints intentionally mirror the Python agent surface where practical, returning the same `modict`/dict-backed payloads used internally.
+
+Key endpoints:
+
+```text
+GET  /health
+GET  /status
+GET  /config
+GET  /session
+GET  /sessions
+GET  /messages
+GET  /memory
+GET  /tools
+GET  /wakeups
+GET  /events
+GET  /events/replay
+POST /turns
+POST /interrupt
+POST /tui/open
+POST /tui/close
+POST /restart
+```
+
+The TUI is a visual client only. It connects over SSE, replays the latest turn when opened mid-session, tracks event sequence cursors, and reconnects after server restarts or transient stream loss. The server accepts one TUI client at a time, while allowing the same client process to replace a stale SSE subscription during reconnect.
+
+The tray can start or stop the user service, open or close the TUI, and keep the local agent available independently of the terminal UI.
+
 ## Extending the agent
 
 ### Define a tool
@@ -329,7 +385,7 @@ The tests isolate `AGENT_RUNTIME_DIR` automatically, so they should not create o
 Current baseline:
 
 ```text
-102 passed
+293 passed
 ```
 
 ## Packaging
@@ -344,11 +400,14 @@ python -m build
 The distribution includes prompt text files and `codex_agent/get_text/default_gitignore` through package data and `MANIFEST.in`.
 
 ## Recent changes
+- `0.1.9`: maintenance packaging release after validating the local execution environment and deploy workflow.
+- `0.1.8`: scope TUI replay/SSE catch-up to the active session and make bash/python subprocesses inherit the project Python environment, including service-launched agents.
+- `0.1.7`: add durable RAG memory, scheduled wakeups, process-isolated server runtime, tray/service controls, robust SSE replay/reconnect, richer TUI status, and improved token estimates.
+- `0.1.6`: add the FastAPI REST/SSE bridge, HTTP/SSE client, async-style agent mainloop, and decoupled TUI operation.
 - `0.1.5`: refine the Textual chat UI with pure black backgrounds, subtler markers/scrollbars, and English UI labels.
 - `0.1.4`: make the Textual REPL UI the default, add multiline input, assistant turn/step events, cleaner tool-call rendering, and `/voice` configuration.
 - `0.1.3`: pass the current session id as `prompt_cache_key` to the Codex backend for prompt cache reuse.
 - `0.1.2`: add `/clear` in the terminal chat to clear the screen without changing session history.
-- `0.1.1`: image observations are now validated before session persistence, preventing broken `ImageMessage` entries from poisoning later turns.
 
 ## Safety notes
 

{codex_agent_framework-0.1.6 → codex_agent_framework-0.1.9}/README.md

@@ -8,19 +8,23 @@ It provides a reusable `Agent` abstraction with persistent sessions, local tools
 
 ## Highlights
 
-- Interactive terminal agent exposed as `codex-agent`.
+- Local FastAPI agent server with a terminal TUI client and GTK tray controller.
+- Process-isolated agent runtime so the local server stays responsive while the agent works.
 - Persistent JSON sessions with `latest`, explicit session IDs, and session navigation commands.
+- Durable RAG memory backed by runtime JSON, with semantic search and automatic turn summaries.
+- Scheduled wakeups for one-shot or periodic autonomous agent turns.
 - Built-in local tools for reading, writing, editing, showing, observing, Bash, and Python execution.
 - Extensible tool, command, and provider decorators.
 - Event-driven internals for UI, streaming, voice, and automation integrations.
 - Document extraction helpers for folders, text files, URLs, PDFs, DOCX, XLSX, ODT, HTML, and more.
-- Optional image generation, image observation, voice, LaTeX, and Streamlit-oriented integration points.
+- Optional image generation, image observation, voice, and LaTeX integration points.
 - Packaged prompt assets and runtime defaults.
 
 ## Requirements
 
 - 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.
 - Firefox / GeckoDriver may be needed for Selenium-backed web extraction paths.
 
 ## Installation
@@ -37,18 +41,36 @@ For development:
 python -m pip install -e '.[dev]'
 ```
 
-Optional Streamlit support:
+## Quick start
+
+Run the local server plus terminal TUI:
 
 ```bash
-python -m pip install -e '.[streamlit]'
+codex-agent
 ```
 
-## Quick start
+Run only the long-lived local server:
+
+```bash
+codex-agent server
+```
 
-Run the bundled terminal assistant:
+Connect a TUI to an already running server:
 
 ```bash
-codex-agent
+codex-agent chat
+```
+
+Start only the tray controller:
+
+```bash
+codex-agent tray
+```
+
+Install the user services for the server and tray controller:
+
+```bash
+codex-agent install-service
 ```
 
 Or use the agent from Python:
@@ -91,6 +113,9 @@ tools/         user runtime tools
 providers/     user runtime context providers
 commands/      user runtime slash commands
 images/        generated or persisted image outputs
+memory.json    durable RAG memory entries
+wakeups.json   scheduled autonomous wakeups
+tui.json       currently registered TUI client process
 ```
 
 You can override the runtime location with:
@@ -145,9 +170,41 @@ The default agent registers local tools that can be exposed to the model:
 | `bash` | Execute shell commands. |
 | `observe` | Load an image into the conversation for visual analysis. |
 | `show` | Open a file, folder, or URL with the system default app/browser. |
+| `memory_add` / `memory_edit` / `memory_delete` / `memory_search` | Manage durable semantic memory entries. |
+| `schedule_wakeup` / `cancel_wakeup` / `list_wakeups` | Manage automatic future turns. |
+| `open_tui` / `close_tui` | Open or close the local TUI through the running server. |
 
 Use these with care: Bash, Python, write, and edit run with the current user's privileges.
 
+## Local server, TUI, and tray
+
+The server exposes the agent through a thin FastAPI bridge. Its REST and SSE endpoints intentionally mirror the Python agent surface where practical, returning the same `modict`/dict-backed payloads used internally.
+
+Key endpoints:
+
+```text
+GET  /health
+GET  /status
+GET  /config
+GET  /session
+GET  /sessions
+GET  /messages
+GET  /memory
+GET  /tools
+GET  /wakeups
+GET  /events
+GET  /events/replay
+POST /turns
+POST /interrupt
+POST /tui/open
+POST /tui/close
+POST /restart
+```
+
+The TUI is a visual client only. It connects over SSE, replays the latest turn when opened mid-session, tracks event sequence cursors, and reconnects after server restarts or transient stream loss. The server accepts one TUI client at a time, while allowing the same client process to replace a stale SSE subscription during reconnect.
+
+The tray can start or stop the user service, open or close the TUI, and keep the local agent available independently of the terminal UI.
+
 ## Extending the agent
 
 ### Define a tool
@@ -280,7 +337,7 @@ The tests isolate `AGENT_RUNTIME_DIR` automatically, so they should not create o
 Current baseline:
 
 ```text
-102 passed
+293 passed
 ```
 
 ## Packaging
@@ -295,11 +352,14 @@ python -m build
 The distribution includes prompt text files and `codex_agent/get_text/default_gitignore` through package data and `MANIFEST.in`.
 
 ## Recent changes
+- `0.1.9`: maintenance packaging release after validating the local execution environment and deploy workflow.
+- `0.1.8`: scope TUI replay/SSE catch-up to the active session and make bash/python subprocesses inherit the project Python environment, including service-launched agents.
+- `0.1.7`: add durable RAG memory, scheduled wakeups, process-isolated server runtime, tray/service controls, robust SSE replay/reconnect, richer TUI status, and improved token estimates.
+- `0.1.6`: add the FastAPI REST/SSE bridge, HTTP/SSE client, async-style agent mainloop, and decoupled TUI operation.
 - `0.1.5`: refine the Textual chat UI with pure black backgrounds, subtler markers/scrollbars, and English UI labels.
 - `0.1.4`: make the Textual REPL UI the default, add multiline input, assistant turn/step events, cleaner tool-call rendering, and `/voice` configuration.
 - `0.1.3`: pass the current session id as `prompt_cache_key` to the Codex backend for prompt cache reuse.
 - `0.1.2`: add `/clear` in the terminal chat to clear the screen without changing session history.
-- `0.1.1`: image observations are now validated before session persistence, preventing broken `ImageMessage` entries from poisoning later turns.
 
 ## Safety notes
 

{codex_agent_framework-0.1.6 → codex_agent_framework-0.1.9}/codex_agent/__init__.py

@@ -12,6 +12,8 @@ from .event import (
     AssistantTurnEndEvent,
     AssistantTurnStartEvent,
     AudioPlaybackEvent,
+    CompactionCompletedEvent,
+    CompactionRequestedEvent,
     Event,
     EventBus,
     MessageAddedEvent,

codex_agent_framework-0.1.9/codex_agent/__main__.py

@@ -0,0 +1,107 @@
+from pathlib import Path
+
+from . import Agent
+from .chat import Chat
+from .server import create_app
+from .service import install_user_service, uninstall_user_service
+from .tray import run_tray
+from .utils import load_runtime_env
+
+
+def default_agent_kwargs(host=None, port=None):
+    package_dir = Path(__file__).parent
+    kwargs = dict(
+        system=str(package_dir / 'prompts' / 'system_prompt.txt'),
+        voice_instructions="You're a lively and friendly female in her mid twenties. You speak french with a easy-going and cheerful tone.",
+        username="Baptiste",
+        userage="40",
+    )
+    if host is not None and port is not None:
+        kwargs["server_url"] = f"http://{host}:{port}"
+    return kwargs
+
+
+def default_agent():
+    return Agent(**default_agent_kwargs())
+
+
+def configure_server_url(agent, host, port):
+    if hasattr(agent, "update_config"):
+        agent.update_config(server_url=f"http://{host}:{port}", save=False)
+    return agent
+
+
+def run_server(host="127.0.0.1", port=8765):
+    import uvicorn
+
+    app = create_app(process_agent=True, **default_agent_kwargs(host, port))
+    if hasattr(app, "state") and hasattr(app.state, "agent_service"):
+        app.state.agent_service.start()
+    uvicorn.run(app, host=host, port=port, timeout_graceful_shutdown=2)
+
+
+def run_chat(base_url="http://127.0.0.1:8765"):
+    Chat(base_url=base_url).run()
+
+
+def run_tray_mode(base_url="http://127.0.0.1:8765"):
+    run_tray(base_url=base_url)
+
+
+def run_local(host="127.0.0.1", port=8765):
+    import threading
+    import time
+
+    import uvicorn
+
+    app = create_app(process_agent=True, **default_agent_kwargs(host, port))
+    if hasattr(app, "state") and hasattr(app.state, "agent_service"):
+        app.state.agent_service.start()
+    config = uvicorn.Config(app, host=host, port=port, log_level="warning", timeout_graceful_shutdown=2)
+    server = uvicorn.Server(config)
+    thread = threading.Thread(target=server.run, name="codex-agent-server", daemon=True)
+    thread.start()
+    time.sleep(0.4)
+    try:
+        run_chat(f"http://{host}:{port}")
+    finally:
+        server.should_exit = True
+        thread.join(timeout=1.0)
+
+
+def main(argv=None):
+    import argparse
+
+    load_runtime_env()
+
+    parser = argparse.ArgumentParser(prog="codex-agent")
+    parser.add_argument(
+        "mode",
+        nargs="?",
+        choices=["local", "server", "chat", "tray", "install-service", "uninstall-service"],
+        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.",
+    )
+    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)
+
+    if args.mode == "server":
+        run_server(args.host, args.port)
+    elif args.mode == "chat":
+        run_chat(args.url or f"http://{args.host}:{args.port}")
+    elif args.mode == "tray":
+        run_tray_mode(args.url or f"http://{args.host}:{args.port}")
+    elif args.mode == "install-service":
+        path = install_user_service(host=args.host, port=args.port, enable=True, start=True)
+        print(f"Installed and started user service: {path}")
+    elif args.mode == "uninstall-service":
+        path = uninstall_user_service(disable=True, stop=True)
+        print(f"Uninstalled user service: {path}")
+    else:
+        run_local(args.host, args.port)
+
+
+if __name__ == '__main__':
+    main()