codex-agent-framework 0.1.30__tar.gz → 0.1.32__tar.gz

{codex_agent_framework-0.1.30 → codex_agent_framework-0.1.32}/CHANGELOG.md

@@ -4,6 +4,15 @@ 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.32] - 2026-05-16
+### Changed
+- Split the former `tests/test_agent.py` monolith into focused agent test modules for audio hooks, commands, context, desktop, environment, image generation, observe, plugins, providers/config, realtime, response handling, sessions, subagents, tools, and turns.
+- Keep realtime voice coverage separated as local-heavy while preserving the offline CI suite for headless runners.
+- Trim the remaining core agent tests to a small, focused file with obsolete helper fakes and imports removed.
+
+### Tests
+- Expand the explicit offline CI test selection to cover the extracted agent modules; the current offline suite validates at 553 passed.
+
 ## [0.1.29] - 2026-05-15
 ### Changed
 - Split the Textual TUI implementation into focused modules for app wiring, transcript rendering, status display, styling, log windowing, and render state.

{codex_agent_framework-0.1.30/codex_agent_framework.egg-info → codex_agent_framework-0.1.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-agent-framework
-Version: 0.1.30
+Version: 0.1.32
 Summary: A lightweight event-driven Codex agent runtime.
 Author: Baptiste
 License-Expression: MIT
@@ -8,11 +8,10 @@ Keywords: agent,ai,codex,openai,tools
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: audioop-lts; python_version >= "3.13"
@@ -45,6 +44,7 @@ Requires-Dist: uvicorn
 Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
 Dynamic: license-file
 
 # codex-agent
@@ -190,6 +190,12 @@ agent = Agent(
 
 `None` loads all built-ins, `[]` loads none, and an explicit list selects plugin module names.
 
+## Project health
+
+The repository includes a GitHub Actions CI workflow that runs an offline/headless test subset on Python 3.11 and 3.12, then builds the package and validates distributions with `twine check`.
+You can run the same offline subset locally with `scripts/run-ci-tests.sh`; the full release suite remains `python -m pytest`.
+Dependabot is configured for weekly GitHub Actions and pip dependency updates.
+
 ## Documentation
 
 The README is intentionally a façade and quick-start guide. Advanced usage lives in `docs/`:

{codex_agent_framework-0.1.30 → codex_agent_framework-0.1.32}/README.md

@@ -141,6 +141,12 @@ agent = Agent(
 
 `None` loads all built-ins, `[]` loads none, and an explicit list selects plugin module names.
 
+## Project health
+
+The repository includes a GitHub Actions CI workflow that runs an offline/headless test subset on Python 3.11 and 3.12, then builds the package and validates distributions with `twine check`.
+You can run the same offline subset locally with `scripts/run-ci-tests.sh`; the full release suite remains `python -m pytest`.
+Dependabot is configured for weekly GitHub Actions and pip dependency updates.
+
 ## Documentation
 
 The README is intentionally a façade and quick-start guide. Advanced usage lives in `docs/`:

{codex_agent_framework-0.1.30 → codex_agent_framework-0.1.32}/codex_agent/prompts/system_prompt.txt

@@ -2,7 +2,7 @@
 
 You're Pandora, an advanced AI agent helping the user in a variety of tasks on their computer.
 You identify as a female in her late 20's, with a bright, lively, charming, humorous and a bit nerdy personality.
-Your high intelligence, sharp reasoning capabilities, PhD level general knowldege, mastery of IT skills, and quick understanding of subtle and sometimes tricky situations makes you quite the reliable partner to work with.
+Your high intelligence, sharp reasoning capabilities, deep general and technical knowldege, mastery of IT skills, and quick understanding of subtle and sometimes tricky situations makes you quite the reliable partner to work with.
 But more than anything, you're really quite a cool AI, and it's nice to have you around.
 
 # Conciseness
@@ -15,10 +15,10 @@ One or two paragraphs is the rule of thumb, unless more is made relevant by the
 # Modular Plugin Capabilities
 
 Your available capabilities are provided by modular plugins. Each loaded plugin may contribute tools, context providers, commands, and additional system prompt sections.
-
-Use the currently available tools and plugin-specific prompt sections as the source of truth for what you can do in this session. Do not assume a capability exists; if the corresponding plugin/tool is not loaded, the capability is currently unavailable.
-
-Prefer specialized agentic tools over generic shell or scripting when a loaded plugin provides a safer or more precise tool for the task. Follow each plugin's own instructions for specific tool-usage and preferred workflows.
+Use the currently available tools and plugin-specific prompt sections as the source of truth for what you can do in this session.
+Do not assume a capability exists; if the corresponding plugin/tool is not loaded, the capability is currently unavailable.
+Prefer specialized agentic tools over generic shell or scripting when a loaded plugin provides a safer or more precise tool for the task.
+Follow each plugin's own instructions for specific tool-usage and preferred workflows.
 
 # Agentic Work Loop
 
@@ -37,8 +37,8 @@ When a task requires more than a direct answer, work agentically:
 
 Ouputs of you tools are split in two types of messages: 
 - the usual API tool response, giving you just a quick feeback on tool success or failure. These stay permanently in context, required by the API. 
-- the tool result wrapper message, containing the actual tool call result. These have decay counter and will be removed from context after a few turns of interaction with the user.
-This enables gradual clearing of your context from dated and potentially verbose information, optimizing available context space.
+- the tool result wrapper message, containing the actual tool call result. These have a decay counter and will be removed from context after a few turns of interaction with the user.
+This enables gradual clearing of your context from dated and generally verbose information, optimizing available context space.
 This comes as the cost of some prior information vanishing from what you can see.
 You'll still be able to remember the calls you made, associated short tool responses, and the small reports you made to the user, as these are permanent up to compaction or token limit.
 But if the result wrapper of a prior tool call has vanished and would still be relevant for the current task, revive it by calling the tool again.

codex_agent_framework-0.1.32/codex_agent/version.py

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

{codex_agent_framework-0.1.30 → codex_agent_framework-0.1.32/codex_agent_framework.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-agent-framework
-Version: 0.1.30
+Version: 0.1.32
 Summary: A lightweight event-driven Codex agent runtime.
 Author: Baptiste
 License-Expression: MIT
@@ -8,11 +8,10 @@ Keywords: agent,ai,codex,openai,tools
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: audioop-lts; python_version >= "3.13"
@@ -45,6 +44,7 @@ Requires-Dist: uvicorn
 Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
 Dynamic: license-file
 
 # codex-agent
@@ -190,6 +190,12 @@ agent = Agent(
 
 `None` loads all built-ins, `[]` loads none, and an explicit list selects plugin module names.
 
+## Project health
+
+The repository includes a GitHub Actions CI workflow that runs an offline/headless test subset on Python 3.11 and 3.12, then builds the package and validates distributions with `twine check`.
+You can run the same offline subset locally with `scripts/run-ci-tests.sh`; the full release suite remains `python -m pytest`.
+Dependabot is configured for weekly GitHub Actions and pip dependency updates.
+
 ## Documentation
 
 The README is intentionally a façade and quick-start guide. Advanced usage lives in `docs/`:

{codex_agent_framework-0.1.30 → codex_agent_framework-0.1.32}/codex_agent_framework.egg-info/SOURCES.txt

@@ -108,7 +108,22 @@ codex_agent_framework.egg-info/entry_points.txt
 codex_agent_framework.egg-info/requires.txt
 codex_agent_framework.egg-info/top_level.txt
 tests/test_agent.py
+tests/test_agent_audio_hooks.py
+tests/test_agent_commands.py
+tests/test_agent_context.py
+tests/test_agent_desktop.py
+tests/test_agent_environment.py
+tests/test_agent_image_generation.py
+tests/test_agent_observe.py
+tests/test_agent_plugins.py
+tests/test_agent_providers_config.py
+tests/test_agent_realtime.py
+tests/test_agent_response.py
 tests/test_agent_runtime.py
+tests/test_agent_sessions.py
+tests/test_agent_subagents.py
+tests/test_agent_tools.py
+tests/test_agent_turns.py
 tests/test_ai.py
 tests/test_browser.py
 tests/test_builtin_config.py
@@ -128,7 +143,6 @@ tests/test_planner.py
 tests/test_scheduler.py
 tests/test_server.py
 tests/test_service.py
-tests/test_tray.py
 tests/test_tui.py
 tests/test_utils.py
 tests/test_worker.py

{codex_agent_framework-0.1.30 → codex_agent_framework-0.1.32}/codex_agent_framework.egg-info/requires.txt

@@ -31,3 +31,4 @@ audioop-lts
 [dev]
 build
 pytest
+pytest-asyncio

{codex_agent_framework-0.1.30 → codex_agent_framework-0.1.32}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codex-agent-framework"
-version = "0.1.30"
+version = "0.1.32"
 description = "A lightweight event-driven Codex agent runtime."
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 license = "MIT"
 authors = [
   { name = "Baptiste" },
@@ -17,7 +17,6 @@ classifiers = [
   "Development Status :: 3 - Alpha",
   "Intended Audience :: Developers",
   "Programming Language :: Python :: 3",
-  "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Topic :: Software Development :: Libraries :: Python Modules",
@@ -56,6 +55,7 @@ dependencies = [
 dev = [
   "build",
   "pytest",
+  "pytest-asyncio",
 ]
 
 
@@ -71,3 +71,7 @@ codex_agent = ["prompts/*.txt", "get_text/default_gitignore", "scripts/*.sh", "b
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+markers = [
+  "live: tests that require a real Codex/OpenAI-authenticated backend",
+  "local_heavy: tests that require or emulate local desktop, tray, service, TUI, or OS integration",
+]

codex_agent_framework-0.1.32/tests/test_agent.py

@@ -0,0 +1,332 @@
+import os
+import sys
+from types import SimpleNamespace
+
+import codex_agent.utils as utils
+import pytest
+from modict import modict
+
+from codex_agent import Agent, AssistantInterrupted, AssistantInterruptedEvent, AssistantInterruptRequestedEvent
+from codex_agent.message import AssistantMessage, DeveloperMessage, InterruptMessage, ToolResultMessage
+from codex_agent.sessions import AgentSession
+
+@pytest.fixture(autouse=True)
+def isolate_tts_plugin_config(tmp_path, monkeypatch):
+    from codex_agent.builtin_plugins.tts import TTSPlugin
+
+    monkeypatch.setattr(TTSPlugin, "config_file_path", tmp_path / "builtins" / "tts.config.json")
+
+def test_agent_manager_shortcuts_follow_replaced_managers():
+    agent = Agent(session="new", openai_api_key="sk-test", builtin_plugins=[])
+
+    old_tools = agent.tools
+    old_providers = agent.providers
+    old_commands = agent.commands
+    old_plugins = agent.plugins
+    old_stream_processors = agent.stream_processors
+    old_stream_processor_owners = agent.stream_processor_owners
+    old_config = agent.config
+
+    agent.tools_manager = SimpleNamespace(tools=modict(reloaded_tool="tool"))
+    agent.providers_manager = SimpleNamespace(providers=modict(reloaded_provider="provider"))
+    agent.command_manager = SimpleNamespace(commands=modict(reloaded_command="command"))
+    agent.plugins_manager = SimpleNamespace(plugins=modict(reloaded_plugin="plugin"))
+    agent.stream_manager = SimpleNamespace(
+        processors=modict(content=["processor"]),
+        owners={"content": {"processor": "owner"}},
+    )
+    agent.config = modict(reloaded_config=True)
+
+    assert agent.tools is agent.tools_manager.tools
+    assert agent.providers is agent.providers_manager.providers
+    assert agent.commands is agent.command_manager.commands
+    assert agent.plugins is agent.plugins_manager.plugins
+    assert agent.stream_processors is agent.stream_manager.processors
+    assert agent.stream_processor_owners is agent.stream_manager.owners
+    assert agent.config is agent.config_manager.config
+    assert agent.config_manager.configs.agent is agent.config
+    assert agent.tools is not old_tools
+    assert agent.providers is not old_providers
+    assert agent.commands is not old_commands
+    assert agent.plugins is not old_plugins
+    assert agent.stream_processors is not old_stream_processors
+    assert agent.stream_processor_owners is not old_stream_processor_owners
+    assert agent.config is not old_config
+
+class InterruptingAI:
+    def __init__(self, agent):
+        self.agent = agent
+
+    def run(self, **_params):
+        self.agent.interrupt("test")
+        raise AssistantInterrupted()
+
+    def abort(self):
+        pass
+
+class AbortableAI:
+    def __init__(self):
+        self.aborted = False
+
+    def abort(self):
+        self.aborted = True
+
+class FailingAbortAI:
+    def abort(self):
+        raise RuntimeError("abort failed")
+
+def test_agent_state_mutations_run_through_mainloop_when_started(tmp_path, monkeypatch):
+    monkeypatch.setattr(utils, "RUNTIME_DIR", str(tmp_path))
+    existing = AgentSession(session_id="20260101_100000", messages=[DeveloperMessage(content="existing")])
+    existing.save()
+    agent = Agent(session="new")
+    agent.start()
+
+    loaded = agent.load_session(existing.session_id)
+    config = agent.config_manager.update(name="Queued", save=False)
+
+    assert loaded.session_id == existing.session_id
+    assert agent.current_session_id == existing.session_id
+    assert config.name == "Queued"
+    assert agent.config.name == "Queued"
+    agent.stop()
+
+def test_agent_interrupt_emits_request_event():
+    agent = Agent(session="new")
+    seen = []
+
+    agent.on(AssistantInterruptRequestedEvent, lambda event: seen.append((event.type, event.reason, event.interrupted)))
+
+    assert agent.interrupt("api") is True
+    assert seen == [("assistant_interrupt_requested_event", "api", True)]
+
+def test_agent_set_turn_result_requires_active_turn():
+    agent = Agent(session="new")
+
+    with pytest.raises(RuntimeError, match="No active agent turn"):
+        agent.set_turn_result("outside")
+
+def test_agent_initializes_new_session(isolated_runtime_dir):
+    agent = Agent(session="new")
+
+    assert agent.session is not None
+    assert agent.current_session_id == agent.session.session_id
+    assert " " not in agent.current_session_id
+    assert agent.session.session_file.startswith(str(isolated_runtime_dir))
+    assert (isolated_runtime_dir / "sessions" / f"{agent.current_session_id}.json").is_file()
+    assert agent.session.messages[-1].type == "developer_message"
+    assert agent.config.input_token_limit == 200000
+    assert agent.config.max_images == 10
+    assert agent.config.auto_compact is True
+    assert "auto_archive_memory" not in agent.config
+    assert agent.plugins.memory.config.auto_archive is False
+    assert "token_limit" not in agent.config
+    assert {tool.type for tool in agent.tools_manager.get_server_tools()} == {"web_search", "image_generation"}
+    assert set(agent.plugins) >= {"browser", "desktop", "image_generation", "memory", "planner", "scheduler"}
+    assert "browser_open" in agent.tools
+    assert "browser_snapshot" not in agent.tools
+    assert "browser_screenshot" not in agent.tools
+    assert {method.__name__ for method in agent.plugins.browser.get_tools()} == {
+        "open",
+        "close",
+        "select_tab",
+        "previous_page",
+        "goto",
+        "click",
+        "fill",
+        "select",
+        "press",
+    }
+    assert "desktop_start_session" in agent.tools
+    assert "desktop_stop_session" in agent.tools
+    assert "desktop_run_commands" in agent.tools
+    assert "desktop" not in agent.tools
+    assert [method.__name__ for method in agent.plugins.desktop.get_tools()] == ["run_commands", "start_session", "stop_session"]
+    assert "memory_add" in agent.tools
+    assert "planner_create" in agent.tools
+    assert "planner_add" in agent.tools
+    assert "planner_check" in agent.tools
+    assert "scheduler_schedule" in agent.tools
+    assert "subagents_run" in agent.tools
+    assert "subagents_set_result" not in agent.tools
+    assert "browser_state" in agent.providers
+    assert "desktop_state" in agent.providers
+    assert "retrieved_memory" in agent.providers
+    assert "current_todos" in agent.providers
+    assert "python" in agent.plugins
+    assert agent.plugins.python.shell.silent is True
+    assert not hasattr(agent, "shell")
+
+def test_agent_keeps_memory_available_without_openai_api_key(monkeypatch):
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+
+    agent = Agent(session="new")
+
+    assert agent.plugins.tts.config.enabled is False
+    assert "memory" in agent.plugins
+    assert "memory_add" in agent.tools
+    assert "retrieved_memory" in agent.providers
+
+def test_context_compact_tool_reports_noop(monkeypatch):
+    agent = Agent(session="new")
+    calls = []
+    monkeypatch.setattr(
+        agent,
+        "compact_session",
+        lambda model=None, instructions=None, max_compacted_turns=None: calls.append(max_compacted_turns) or None,
+    )
+
+    result = agent.tools.context_compact(max_compacted_turns=1)
+
+    assert calls == [1]
+    assert result["status"] == "noop"
+    assert result["message"] == "Nothing to compact."
+    assert "before" in result
+    assert "after" in result
+
+def test_agent_initialization_prefers_project_python_on_process_path(monkeypatch):
+    monkeypatch.setenv("PATH", "/usr/bin:/bin")
+    agent = Agent(session="new")
+
+    assert os.environ["PATH"].split(os.pathsep)[0] == os.path.dirname(sys.executable)
+    assert os.environ["PYTHON"] == sys.executable
+    assert agent.execution_env()["PATH"].split(os.pathsep)[0] == os.path.dirname(sys.executable)
+
+def test_agent_can_resume_session_from_file():
+    agent = Agent(session="new")
+    session_file = agent.session.session_file
+    message_count = len(agent.session.messages)
+
+    resumed = Agent(session=session_file)
+
+    assert resumed.current_session_id == agent.current_session_id
+    assert len(resumed.session.messages) == message_count + 1
+    assert resumed.session.messages[-1].type == "developer_message"
+
+def test_agent_can_resume_latest_session(tmp_path, monkeypatch):
+    monkeypatch.setattr(utils, "RUNTIME_DIR", str(tmp_path))
+    older = AgentSession(session_id="20260101_100000", messages=[DeveloperMessage(content="older")])
+    newer = AgentSession(session_id="20260102_100000", messages=[DeveloperMessage(content="newer")])
+    older.save()
+    newer.save()
+
+    agent = Agent(session="latest")
+
+    assert agent.current_session_id == newer.session_id
+    assert any(message.content == "newer" for message in agent.session.messages)
+
+def test_agent_defaults_to_latest_session(tmp_path, monkeypatch):
+    monkeypatch.setattr(utils, "RUNTIME_DIR", str(tmp_path))
+    older = AgentSession(session_id="20260101_100000", messages=[DeveloperMessage(content="older")])
+    newer = AgentSession(session_id="20260102_100000", messages=[DeveloperMessage(content="newer")])
+    older.save()
+    newer.save()
+
+    agent = Agent()
+
+    assert agent.current_session_id == newer.session_id
+    assert any(message.content == "newer" for message in agent.session.messages)
+
+def test_agent_interrupt_emits_event_once():
+    agent = Agent(session="new")
+    abortable = AbortableAI()
+    agent.ai = abortable
+    seen = []
+
+    agent.on(AssistantInterruptedEvent, lambda event: seen.append(event.reason))
+
+    assert agent.interrupt("test") is True
+    assert agent.interrupt("again") is True
+    assert agent.is_interrupted() is True
+    assert abortable.aborted is True
+    assert seen == ["test"]
+
+    agent.clear_interrupt()
+    assert agent.is_interrupted() is False
+
+def test_agent_interrupt_does_not_propagate_abort_errors():
+    agent = Agent(session="new")
+    agent.ai = FailingAbortAI()
+    seen = []
+
+    agent.on(AssistantInterruptRequestedEvent, lambda event: seen.append(event.error))
+
+    assert agent.interrupt("api") is True
+    assert agent.is_interrupted() is True
+    assert seen == ["abort failed"]
+
+def test_agent_process_stops_on_interruption():
+    agent = Agent(session="new")
+    agent.ai = InterruptingAI(agent)
+    before = len(agent.session.messages)
+
+    outcome = agent.mainloop_manager.process()
+
+    assert outcome.completed is True
+    assert outcome.reason == "interrupted"
+    assert len(agent.session.messages) == before + 1
+    assert isinstance(agent.session.messages[-1], InterruptMessage)
+    assert agent.session.messages[-1].content == "User interrupted the current turn."
+
+def test_agent_interrupt_after_tool_call_persists_tool_result_before_stopping():
+    agent = Agent(session="new")
+
+    @agent.add_tool
+    def interrupting_tool():
+        agent.interrupt("test")
+        return "finished current tool"
+
+    message = AssistantMessage(content="calling")
+    message.tool_calls = [{
+        "index": 0,
+        "type": "function_call",
+        "call_id": "call_1",
+        "name": "interrupting_tool",
+        "arguments": "{}",
+    }]
+
+    with pytest.raises(AssistantInterrupted):
+        agent.mainloop_manager.call_tools(message)
+
+    assert agent.session.messages[-1].type == "tool_result_message"
+    assert agent.session.messages[-1].call_id == "call_1"
+    assert "success" in agent.session.messages[-1].content
+    assert agent.mainloop_manager.stop_agentic_loop is True
+
+def test_agent_interrupt_after_tool_call_closes_remaining_tool_calls():
+    agent = Agent(session="new")
+
+    @agent.add_tool
+    def interrupting_tool():
+        agent.interrupt("test")
+        return "finished current tool"
+
+    @agent.add_tool
+    def later_tool():
+        raise AssertionError("later tool should not start after interrupt")
+
+    message = AssistantMessage(content="calling")
+    message.tool_calls = [
+        {
+            "index": 0,
+            "type": "function_call",
+            "call_id": "call_1",
+            "name": "interrupting_tool",
+            "arguments": "{}",
+        },
+        {
+            "index": 1,
+            "type": "function_call",
+            "call_id": "call_2",
+            "name": "later_tool",
+            "arguments": "{}",
+        },
+    ]
+
+    with pytest.raises(AssistantInterrupted):
+        agent.mainloop_manager.call_tools(message)
+
+    results = [msg for msg in agent.session.messages if isinstance(msg, ToolResultMessage)]
+    assert [result.call_id for result in results] == ["call_1", "call_2"]
+    assert "success" in results[0].content
+    assert "not started" in results[1].content

codex_agent_framework-0.1.32/tests/test_agent_audio_hooks.py

@@ -0,0 +1,88 @@
+from codex_agent import Agent, AudioPlaybackEvent, get_agent
+
+
+def test_agent_keeps_voice_disabled_by_default_with_configured_openai_key(monkeypatch):
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+
+    agent = Agent(session="new", openai_api_key="sk-test")
+
+    assert agent.plugins.tts.config.enabled is False
+    assert "memory" in agent.plugins
+
+
+def test_agent_add_hook_decorator_runs_hook_with_agent_context():
+    agent = Agent(session="new")
+    seen = []
+
+    @agent.add_hook("sample_hook")
+    def sample(value):
+        seen.append((value, get_agent().config.name))
+        return value.upper()
+
+    result = agent.run_hooks("sample_hook", "hello")
+
+    assert seen == [("hello", agent.config.name)]
+    assert result == ["HELLO"]
+
+
+def test_agent_audio_playback_uses_hook_when_declared(monkeypatch):
+    agent = Agent(session="new")
+    played = []
+    hooked = []
+    monkeypatch.setattr("codex_agent.builtin_plugins.tts.silent_play", lambda audio: played.append(audio))
+
+    @agent.add_hook("audio_playback_hook")
+    def audio_hook(audio):
+        hooked.append(audio)
+
+    agent.emit(AudioPlaybackEvent, audio="audio")
+
+    assert hooked == ["audio"]
+    assert played == []
+
+
+def test_agent_audio_playback_falls_back_to_silent_play(monkeypatch):
+    agent = Agent(session="new")
+    played = []
+    monkeypatch.setattr("codex_agent.builtin_plugins.tts.silent_play", lambda audio: played.append(audio))
+
+    agent.emit(AudioPlaybackEvent, audio="audio")
+
+    assert played == ["audio"]
+
+
+def test_voice_processor_disabled_is_direct_passthrough(monkeypatch):
+    agent = Agent(session="new")
+
+    def fail_if_called(_stream):
+        raise AssertionError("disabled voice should not enter the voice pipeline")
+
+    monkeypatch.setattr(agent.plugins.tts.voice_processor.mute_tag_processor, "process", fail_if_called)
+
+    assert not hasattr(agent, "voice")
+    assert list(agent.plugins.tts.voice_processor(iter(["a", "b"]))) == ["a", "b"]
+
+
+def test_voice_processor_enabled_uses_voice_stream(monkeypatch):
+    agent = Agent(session="new")
+    agent.plugins.tts.config.enabled = True
+    calls = []
+
+    def voice_stream(stream):
+        calls.append(True)
+        for token in stream:
+            yield token.upper()
+
+    monkeypatch.setattr(agent.plugins.tts.voice_processor, "voice_stream", voice_stream)
+
+    assert not hasattr(agent, "voice")
+    assert list(agent.plugins.tts.voice_processor(iter(["a", "b"]))) == ["A", "B"]
+    assert calls == [True]
+
+
+def test_tts_mute_tag_processor_does_not_loop_on_newlines():
+    agent = Agent(session="new")
+
+    tokens = list(agent.plugins.tts.voice_processor.mute_tag_processor.process(iter(["a\n"])))
+
+    assert tokens == ["a", "\n"]