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

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

@@ -4,6 +4,29 @@ 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.16] - 2026-05-08
+### Fixed
+- Allow agent startup without an OpenAI API key by disabling OpenAI-dependent capabilities such as voice defaults and the built-in memory plugin instead of failing during initialization.
+- Skip automatic memory archiving when the memory plugin is unavailable.
+
+### Tests
+- Add regression coverage for agent initialization with and without an OpenAI API key.
+
+## [0.1.15] - 2026-05-08
+### Added
+- Add `AgentRuntime` as the canonical external runtime contract for HTTP server, headless CLI, in-process, and process-backed integrations.
+- Add structured runtime configuration updates through `PATCH /config`, `AgentClient.update_config()`, and `codex-agent config set`.
+- Add direct built-in selection config for tools, providers, and plugins with `None` meaning all built-ins, an empty list meaning none, and explicit lists selecting named built-ins.
+
+### Changed
+- Split the command line implementation into the `codex_agent.cli` package with root orchestration commands and headless runtime commands.
+- Route server operations through `AgentRuntime` instead of depending on `Agent` internals directly.
+- Update CLI service/interface commands to the explicit `start/stop/restart server|tray` and `open/close tui` forms.
+
+### Tests
+- Add regression coverage for the runtime abstraction, headless CLI, root CLI dispatch, config updates, and built-in selection.
+- Validate the targeted release-regression suite at 82 passing tests.
+
 ## [0.1.14] - 2026-05-07
 ### Added
 - Add a general `HookManager` with compatibility helpers and hook sites around message submission, commands, context/provider calls, runtime module loading, tool calls, shell execution, and file write/edit operations.

{codex_agent_framework-0.1.14/codex_agent_framework.egg-info → codex_agent_framework-0.1.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-agent-framework
-Version: 0.1.14
+Version: 0.1.16
 Summary: A lightweight event-driven Codex agent runtime.
 Author: Baptiste
 License-Expression: MIT
@@ -123,19 +123,29 @@ codex-agent
 Run only the long-lived local server:
 
 ```bash
-codex-agent server
+codex-agent start server
 ```
 
 Connect a TUI to an already running server:
 
 ```bash
-codex-agent chat
+codex-agent open tui
 ```
 
 Start only the tray controller:
 
 ```bash
-codex-agent tray
+codex-agent start tray
+```
+
+Headless runtime examples:
+
+```bash
+codex-agent status --json
+codex-agent tools
+codex-agent config get input_token_limit
+codex-agent config set input_token_limit 128000
+codex-agent run "summarize this repository"
 ```
 
 Install the user services for the server and tray controller:
@@ -259,6 +269,7 @@ Key endpoints:
 GET  /health
 GET  /status
 GET  /config
+PATCH /config
 GET  /session
 GET  /sessions
 GET  /messages
@@ -380,13 +391,17 @@ agent = Agent(
 )
 ```
 
-Configuration is persisted to `agent_config.json` in the runtime directory when updated through agent helpers or slash commands.
+Configuration is persisted to `agent_config.json` in the runtime directory when updated through agent helpers, slash commands, the HTTP API, or `codex-agent config set`.
+
+If no OpenAI API key is configured through `openai_api_key` or `OPENAI_API_KEY`, the agent can still start, but OpenAI-dependent capabilities such as voice defaults and the built-in memory plugin are disabled.
 
 ## Project layout
 
 ```text
 codex_agent/                    Python package
 codex_agent/agent.py            Agent, AgentConfig, AgentSession
+codex_agent/agent_runtime.py    Runtime abstraction for server, CLI, and process adapters
+codex_agent/cli/                Command line interface package
 codex_agent/plugin.py           Stateful plugin base class
 codex_agent/builtin_tools/     Built-in local tools package
 codex_agent/builtin_commands.py Built-in slash commands
@@ -412,7 +427,7 @@ The tests isolate `AGENT_RUNTIME_DIR` automatically, so they should not create o
 Current baseline:
 
 ```text
-412 passed
+82 targeted release-regression tests passed
 ```
 
 ## Packaging
@@ -427,6 +442,8 @@ python -m build
 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.16`: tolerate missing OpenAI API keys at startup by disabling OpenAI-dependent voice and memory features, and skip memory archiving when the memory plugin is unavailable.
+- `0.1.15`: add the `AgentRuntime` interface for server/CLI/process adapters, split the CLI into a package with headless runtime commands, add `codex-agent config set` plus `PATCH /config`, and make built-in tools/providers/plugins configurable.
 - `0.1.14`: add HookManager infrastructure, planner/scheduler robustness fixes, documented system dependencies, `codex-agent install-system-deps`, `codex-agent bootstrap`, and improved TUI SSE reconnect/replay handling.
 - `0.1.13`: reorganize built-in tools into a `codex_agent.builtin_tools` package, keeping the public import surface compatible while separating file, shell, vision, system, and server-tool modules.
 - `0.1.12`: add a persistent Playwright/Chromium browser controller with tab navigation, DOM/action snapshots, screenshots, form/click/key tools, and `browser_goto(url)` for active-tab navigation.

{codex_agent_framework-0.1.14 → codex_agent_framework-0.1.16}/README.md

@@ -74,19 +74,29 @@ codex-agent
 Run only the long-lived local server:
 
 ```bash
-codex-agent server
+codex-agent start server
 ```
 
 Connect a TUI to an already running server:
 
 ```bash
-codex-agent chat
+codex-agent open tui
 ```
 
 Start only the tray controller:
 
 ```bash
-codex-agent tray
+codex-agent start tray
+```
+
+Headless runtime examples:
+
+```bash
+codex-agent status --json
+codex-agent tools
+codex-agent config get input_token_limit
+codex-agent config set input_token_limit 128000
+codex-agent run "summarize this repository"
 ```
 
 Install the user services for the server and tray controller:
@@ -210,6 +220,7 @@ Key endpoints:
 GET  /health
 GET  /status
 GET  /config
+PATCH /config
 GET  /session
 GET  /sessions
 GET  /messages
@@ -331,13 +342,17 @@ agent = Agent(
 )
 ```
 
-Configuration is persisted to `agent_config.json` in the runtime directory when updated through agent helpers or slash commands.
+Configuration is persisted to `agent_config.json` in the runtime directory when updated through agent helpers, slash commands, the HTTP API, or `codex-agent config set`.
+
+If no OpenAI API key is configured through `openai_api_key` or `OPENAI_API_KEY`, the agent can still start, but OpenAI-dependent capabilities such as voice defaults and the built-in memory plugin are disabled.
 
 ## Project layout
 
 ```text
 codex_agent/                    Python package
 codex_agent/agent.py            Agent, AgentConfig, AgentSession
+codex_agent/agent_runtime.py    Runtime abstraction for server, CLI, and process adapters
+codex_agent/cli/                Command line interface package
 codex_agent/plugin.py           Stateful plugin base class
 codex_agent/builtin_tools/     Built-in local tools package
 codex_agent/builtin_commands.py Built-in slash commands
@@ -363,7 +378,7 @@ The tests isolate `AGENT_RUNTIME_DIR` automatically, so they should not create o
 Current baseline:
 
 ```text
-412 passed
+82 targeted release-regression tests passed
 ```
 
 ## Packaging
@@ -378,6 +393,8 @@ python -m build
 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.16`: tolerate missing OpenAI API keys at startup by disabling OpenAI-dependent voice and memory features, and skip memory archiving when the memory plugin is unavailable.
+- `0.1.15`: add the `AgentRuntime` interface for server/CLI/process adapters, split the CLI into a package with headless runtime commands, add `codex-agent config set` plus `PATCH /config`, and make built-in tools/providers/plugins configurable.
 - `0.1.14`: add HookManager infrastructure, planner/scheduler robustness fixes, documented system dependencies, `codex-agent install-system-deps`, `codex-agent bootstrap`, and improved TUI SSE reconnect/replay handling.
 - `0.1.13`: reorganize built-in tools into a `codex_agent.builtin_tools` package, keeping the public import surface compatible while separating file, shell, vision, system, and server-tool modules.
 - `0.1.12`: add a persistent Playwright/Chromium browser controller with tab navigation, DOM/action snapshots, screenshots, form/click/key tools, and `browser_goto(url)` for active-tab navigation.

codex_agent_framework-0.1.16/codex_agent/__main__.py

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

{codex_agent_framework-0.1.14 → codex_agent_framework-0.1.16}/codex_agent/agent.py

@@ -1,4 +1,4 @@
-from .utils import text_content, ensure_runtime_dir, upload_file_to_folder, project_python_env
+from .utils import text_content, ensure_runtime_dir, upload_file_to_folder, project_python_env, runtime_join
 from modict import modict
 import os
 import sys
@@ -17,6 +17,7 @@ from .status import StatusManager
 from .tool import ImageGenerationTool, reset_current_agent, set_current_agent
 from .ai import AIBadRequestError, AIClient
 from .voice import VoiceProcessor
+from .memory import RAGMemory
 from .latex import LaTeXProcessor
 from .event import AgentInterruptRequestedEvent, AgentInterrupted, AgentInterruptedEvent, AudioPlaybackEvent, EventBus
 from pynteract import Shell
@@ -39,6 +40,7 @@ class Agent:
         self.config=self.config_manager.config
         self.config_manager.load()
         self.config_manager.update(kwargs, save=False)
+        self.config_manager.apply_openai_capability_defaults()
         self.events=EventBus()
         self.registry=RegistryManager(self)
         self.tools=self.registry.tools
@@ -65,6 +67,7 @@ class Agent:
         self.registry.init_providers_folder()
         self.command_manager.init_folder()
         self.ai=AIClient(self)
+        self.memory=RAGMemory(file=runtime_join("memory.json"))
         self.voice=VoiceProcessor(self)
         self.latex=LaTeXProcessor()
         self.content_processors=[self.voice]

{codex_agent_framework-0.1.14 → codex_agent_framework-0.1.16}/codex_agent/agent_runtime.py

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

{codex_agent_framework-0.1.14 → codex_agent_framework-0.1.16}/codex_agent/ai.py

@@ -456,6 +456,8 @@ class AIClient:
         if not isinstance(content, str):
             raise ValueError(f"Content must be a string, got {type(content)}")
         content = self.truncate_embedding_input(content, model=model)
+        if not content.strip():
+            raise ValueError("Content must not be empty")
 
         try:
             response = self.client.embeddings.create(
@@ -485,9 +487,13 @@ class AIClient:
         Note:
             OpenAI API handles batching automatically for better performance.
         """
+        if not contents:
+            return []
         if not all(isinstance(content, str) for content in contents):
             raise ValueError("All contents must be strings")
         contents = [self.truncate_embedding_input(content) for content in contents]
+        if any(not content.strip() for content in contents):
+            raise ValueError("Embedding contents must not contain empty strings")
 
         try:
             response = self.client.embeddings.create(
@@ -501,6 +507,14 @@ class AIClient:
 
         return embeddings
 
+    def message_embedding_content(self, msg):
+        if hasattr(msg, 'content') and isinstance(msg.content, str):
+            return msg.content.strip()
+        raise ValueError("Message must have text content")
+
+    def zero_embedding(self, dimensions=128):
+        return [0.0] * int(dimensions)
+
     def similarity(self, emb1, emb2):
         """
         Calculate shifted positive cosine similarity between two embeddings.
@@ -524,15 +538,52 @@ class AIClient:
         Note:
             Only text content is supported.
         """
-        if hasattr(msg, 'content') and isinstance(msg.content, str):
-            content = msg.content
-        else:
-            raise ValueError("Message must have text content")
-
-        # Generate embedding
+        content = self.message_embedding_content(msg)
+        if not content:
+            embedding = self.zero_embedding(dimensions)
+            msg.embedding = embedding
+            return embedding
         embedding = self.embed_content(content, precision, dimensions, model)
-
-        # Assign to msg.embedding
         msg.embedding = embedding
-
         return embedding
+
+    def embed_messages(self, messages, precision=5, dimensions=128, model="text-embedding-3-small"):
+        """
+        Embed multiple Message objects in one embeddings API request and assign
+        the resulting vectors to each message.
+        """
+        messages = list(messages)
+        if not messages:
+            return []
+
+        embeddings = [None] * len(messages)
+        batch = []
+        batch_indices = []
+        for index, msg in enumerate(messages):
+            content = self.message_embedding_content(msg)
+            if not content:
+                embedding = self.zero_embedding(dimensions)
+                msg.embedding = embedding
+                embeddings[index] = embedding
+                continue
+            batch.append(content)
+            batch_indices.append(index)
+
+        if not batch:
+            return embeddings
+
+        batch_embeddings = self.embed_contents(
+            batch,
+            precision=precision,
+            dimensions=dimensions,
+            model=model,
+        )
+        if len(batch_embeddings) != len(batch):
+            raise AIClientError(
+                f"Expected {len(batch)} embeddings, got {len(batch_embeddings)}"
+            )
+        for index, embedding in zip(batch_indices, batch_embeddings):
+            msg = messages[index]
+            msg.embedding = embedding
+            embeddings[index] = embedding
+        return embeddings

codex_agent_framework-0.1.16/codex_agent/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line interface package for codex-agent."""