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

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

@@ -4,6 +4,14 @@ 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.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.egg-info → codex_agent_framework-0.1.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-agent-framework
-Version: 0.1.12
+Version: 0.1.13
 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
@@ -361,9 +363,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 +388,7 @@ The tests isolate `AGENT_RUNTIME_DIR` automatically, so they should not create o
 Current baseline:
 
 ```text
-293 passed
+376 passed
 ```
 
 ## Packaging
@@ -399,6 +403,7 @@ 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.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.13}/README.md

@@ -314,9 +314,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 +339,7 @@ The tests isolate `AGENT_RUNTIME_DIR` automatically, so they should not create o
 Current baseline:
 
 ```text
-293 passed
+376 passed
 ```
 
 ## Packaging
@@ -352,6 +354,7 @@ 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.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.13/codex_agent/__init__.py

@@ -0,0 +1,136 @@
+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,
+    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",
+    "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.13}/codex_agent/__main__.py

@@ -26,8 +26,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
 
 

codex_agent_framework-0.1.13/codex_agent/agent.py

@@ -0,0 +1,425 @@
+from .utils import text_content, ensure_runtime_dir, upload_file_to_folder, project_python_env
+from modict import modict
+import os
+import sys
+from .message import DeveloperMessage, ServerToolResponseMessage, SystemMessage, ToolResultMessage, UserMessage, message_from_data
+from .image import ImageMessage
+from .command import CommandManager
+from .config import ConfigManager
+from .context import ContextManager
+from .mainloop import MainLoopManager
+from .plugin import PluginsManager
+from .registry import RegistryManager
+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 .voice import VoiceProcessor
+from .latex import LaTeXProcessor
+from .event import AgentInterruptRequestedEvent, AgentInterrupted, AgentInterruptedEvent, AudioPlaybackEvent, EventBus
+from pynteract import Shell
+from threading import Event as ThreadEvent
+
+class Agent:
+
+    def __init__(self,shell=None,session="latest",**kwargs):
+        """Initializes the Agent instance with configuration, events, tools, and message history.
+
+        Args:
+            shell: Optional shell instance for code execution. If None, creates a new Shell.
+            session: Session id or JSON session file to resume. Defaults to
+                "latest"; pass "new" to force a fresh session.
+            **kwargs: Additional keyword arguments to update the agent configuration.
+        """
+        ensure_runtime_dir()
+        self.init_execution_environment()
+        self.config_manager=ConfigManager(self)
+        self.config=self.config_manager.config
+        self.config_manager.load()
+        self.config_manager.update(kwargs, save=False)
+        self.events=EventBus()
+        self.registry=RegistryManager(self)
+        self.tools=self.registry.tools
+        self.providers=self.registry.providers
+        self.command_manager=CommandManager(self)
+        self.commands=self.command_manager.commands
+        self.context_manager=ContextManager(self)
+        self.plugins_manager=PluginsManager(self)
+        self.plugins=self.plugins_manager.plugins
+        self.sessions_manager=SessionsManager(self)
+        self.runtime=RuntimeManager(self)
+        self.hooks=modict()
+        self.on(AudioPlaybackEvent, self.handle_audio_playback)
+        self.mainloop_manager=MainLoopManager(self)
+        self._interrupt_requested=ThreadEvent()
+        self.current_session_id=None
+        self.session=None
+        self.status_manager=StatusManager(self)
+        self.shell=None
+        self.init_shell(shell=shell)
+        self.init_workfolder()
+        self.sessions_manager.init_folder()
+        self.registry.init_tools_folder()
+        self.registry.init_providers_folder()
+        self.command_manager.init_folder()
+        self.ai=AIClient(self)
+        self.voice=VoiceProcessor(self)
+        self.latex=LaTeXProcessor()
+        self.content_processors=[self.voice]
+        self.registry.init_builtin_tools()
+        self.registry.init_builtin_providers()
+        self.command_manager.init_builtin()
+        self.plugins_manager.init_builtin()
+        self.registry.init_runtime_tools()
+        self.registry.init_runtime_providers()
+        self.command_manager.init_runtime()
+        self.registry.init_server_tools()
+        self.start_new_session() if session == "new" else self.load_session(session)
+
+    def on(self, event_type, handler=None):
+        """Register an event handler.
+
+        Can be used as ``agent.on(ResponseContentDeltaEvent, handler)`` or as
+        ``@agent.on(ResponseContentDeltaEvent)``.
+        """
+        return self.events.on(event_type, handler)
+
+    def emit(self, event_type, **data):
+        return self.events.emit(event_type, **data)
+
+    @property
+    def busy(self):
+        return self.mainloop_manager.busy
+
+    @property
+    def current_turn_id(self):
+        return self.mainloop_manager.current_turn_id
+
+    def start(self):
+        return self.mainloop_manager.start()
+
+    def stop(self, timeout=None):
+        return self.mainloop_manager.stop(timeout=timeout)
+
+    def submit(self, command, **payload):
+        return self.mainloop_manager.submit(command, **payload)
+
+    def start_turn(self):
+        return self.mainloop_manager.start_turn()
+
+    def submit_command(self, prompt):
+        return self.command_manager.submit(prompt)
+
+    def submit_message(self, message):
+        return self.mainloop_manager.submit_message(message)
+
+    def interrupt(self, reason="user"):
+        abort_error = None
+        if not self._interrupt_requested.is_set():
+            self._interrupt_requested.set()
+            if getattr(self, "ai", None) is not None:
+                try:
+                    self.ai.abort()
+                except Exception as exc:
+                    abort_error = exc
+            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()
+
+    def is_interrupted(self):
+        return self._interrupt_requested.is_set()
+
+    def check_interrupt(self):
+        if self.is_interrupted():
+            raise AgentInterrupted()
+
+    def init_workfolder(self):
+        if not os.path.isdir(self.config.workfolder):
+            os.makedirs(self.config.workfolder,exist_ok=True)
+
+    def init_execution_environment(self):
+        os.environ.update(project_python_env())
+
+    def init_shell(self,shell=None):
+        if shell is None:
+            shell=Shell(silent=True)
+        shell.update_namespace(
+            agent=self,
+            os=os,
+            sys=sys,
+            python_executable=sys.executable,
+        )
+        self.shell=shell
+
+    def execution_env(self):
+        return project_python_env()
+
+    def get_sessions(self):
+        return self.sessions_manager.list()
+
+    def latest_session_id(self):
+        return self.sessions_manager.latest_id()
+
+    def load_session(self, session):
+        return self.sessions_manager.load(session)
+
+    def start_new_session(self):
+        return self.sessions_manager.start_new()
+
+    def delete_session(self, session):
+        return self.sessions_manager.delete(session)
+
+    def navigate_session(self, direction):
+        return self.sessions_manager.navigate(direction)
+
+    def save_session(self):
+        return self.sessions_manager.save()
+
+    def compact_session(self, client=None, model=None, instructions=None):
+        return self.sessions_manager.compact(client=client, model=model, instructions=instructions)
+
+    def add_message(self,msg,pending=False):
+        """Queue a message for the next pending flush, except tool results."""
+        if isinstance(msg, ToolResultMessage):
+            return self.sessions_manager.append_message(msg)
+        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.
+
+        Args:
+            pending: If True, stores message in pending list instead of main messages.
+            **kwargs: Message fields. Must include an explicit ``type``.
+
+        Returns:
+            The created message object.
+        """
+        msg=message_from_data(kwargs)
+        return self.add_message(msg,pending=pending)
+    
+    def add_image(self,source,pending=False,**kwargs):
+        if source:
+            img=ImageMessage(
+                content=source,
+                **kwargs
+            )
+            if not img.is_valid():
+                raise ValueError(f"Invalid or inaccessible image source: {source!r}")
+            self.add_message(img,pending=pending)
+            return img
+
+    def add_tool(self,func=None,name=None,description=None,parameters=None,required=None,tool_type=None,format=None):
+        return self.registry.add_tool(
+            func=func,
+            name=name,
+            description=description,
+            parameters=parameters,
+            required=required,
+            tool_type=tool_type,
+            format=format,
+        )
+
+    def add_provider(self, func=None, name=None):
+        return self.registry.add_provider(func=func, name=name)
+
+    def add_command(self, func=None, name=None):
+        return self.command_manager.add(func, name=name)
+
+    def add_hook(self, key, func=None):
+        """Register a runtime hook.
+
+        Hooks are callable extension points keyed by name. They are runtime
+        functions stored outside persisted payloads, and can be used as
+        ``@agent.add_hook("audio_playback_hook")``.
+        """
+        if func is None:
+            def decorator(f):
+                return self.add_hook(key, f)
+            return decorator
+
+        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
+
+    def has_hook(self, key):
+        return bool(self.hooks.get(key))
+
+    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
+
+    def get_messages(self,filter=None):
+        return self.sessions_manager.messages(filter=filter)
+
+    def get_status(self):
+        return self.status_manager.get_status()
+
+    def create_image(
+        self,
+        prompt,
+        input_images=None,
+        model="gpt-5.4",
+        reasoning_effort="medium",
+        verbosity="medium",
+        output_format="png",
+        size=None,
+        quality=None,
+        background=None,
+        moderation=None,
+    ):
+        """Generate an image directly and return the saved image path."""
+        content = [{"type": "text", "text": prompt}]
+        for source in input_images or []:
+            content.extend(ImageMessage(content=source).content_to_response_parts())
+
+        system_prompt = text_content(os.path.join(os.path.dirname(__file__), "prompts", "image_generation_system_prompt.txt"))
+        message = self.ai.run(
+            messages=[SystemMessage(content=system_prompt), UserMessage(content=content)],
+            tools=[ImageGenerationTool(
+                output_format=output_format,
+                size=size,
+                quality=quality,
+                background=background,
+                moderation=moderation,
+            ).to_response_tool()],
+            model=model,
+            reasoning_effort=reasoning_effort,
+            verbosity=verbosity,
+        )
+        for item in message.output_items:
+            if item.get("type") == "image_generation_call":
+                return ServerToolResponseMessage(item=item).content
+        else:
+            raise RuntimeError("The image_generation tool did not return an image.")
+
+    def get_response(self):
+        """Run the model, emit response events, and store the final message.
+
+        Returns:
+            Message: The aggregated assistant message with content and/or tool calls.
+        """
+        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,
+            )
+            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')
+        )
+        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))
+        return message
+
+    def speak(self,text,**kwargs):
+        audio=self.ai.text_to_audio(text,**kwargs)
+        if audio is not None:
+            self.emit(AudioPlaybackEvent, audio=audio)
+
+    def handle_audio_playback(self, event):
+        audio = event.get("audio")
+        if audio is None:
+            return None
+        if self.has_hook("audio_playback_hook"):
+            return self.run_hooks("audio_playback_hook", audio)
+        from .voice import silent_play
+        return silent_play(audio)
+
+    def listen(self, source, language=None, **kwargs):
+        """
+        description: |
+            Listen to audio input and transcribe it to text, then process it as a user message.
+            Accepts either audio data (BytesIO/bytes) or a file path.
+        parameters:
+            source:
+                description: Audio data as file_path string, BytesIO object or bytes
+            language:
+                description: ISO-639-1 language code (e.g., "en", "fr")
+            kwargs:
+                description: Additional parameters for the transcription (model, prompt, temperature, etc.)
+        """
+
+        transcribed_text = self.transcribe(source, language, **kwargs)
+
+        # Add transcribed text as a user message
+        self.add_message(UserMessage(content=transcribed_text))
+
+    def transcribe(self, source, language=None, **kwargs):
+        """
+        description: |
+            Transcribe audio to text.
+            Accepts either audio data (BytesIO/bytes) or a file path.
+        parameters:
+            source:
+                description: Audio data as file_path string, BytesIO object or bytes
+            language:
+                description: ISO-639-1 language code (e.g., "en", "fr")
+            kwargs:
+                description: Additional parameters for the transcription (model, prompt, temperature, etc.)
+        """
+        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,
+            language=language,
+            **kwargs
+        )
+
+        return transcribed_text
+
+    def upload_file(self, source, name=None):
+        """
+        description: |
+            Upload a file to the agent's workfolder and inform the agent via system message.
+            Supports file paths (str), BytesIO objects, or raw bytes.
+        parameters:
+            source:
+                description: File source - can be a file path (str), BytesIO object, or bytes
+            name:
+                description: Optional name for the file. Required when source is bytes without a name attribute.
+                             Can include extension to override detection.
+        returns:
+            description: Absolute path to the uploaded file
+        """
+        dest_path = upload_file_to_folder(source, self.config.workfolder, name=name)
+        dest_filename = os.path.basename(dest_path)
+
+        self.add_message(DeveloperMessage(content=f"File '{dest_filename}' has been uploaded to the workfolder at: {dest_path}"))
+
+        return dest_path
+
+    def __call__(self,prompt=None)->bool:
+        return self.mainloop_manager.call(prompt=prompt)
+
+    def interact(self):
+        """Starts the interactive Textual chat UI."""
+        from .utils import set_root_path
+        import os
+        if os.environ.get('AGENT_ROOT_PATH') is None:
+            set_root_path(file=__file__)
+        from .chat import Chat
+        Chat(self).run()