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

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

@@ -4,6 +4,21 @@ 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.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.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-agent-framework
-Version: 0.1.14
+Version: 0.1.15
 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,15 @@ 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`.
 
 ## 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 +425,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 +440,7 @@ 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.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.15}/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,15 @@ 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`.
 
 ## 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 +376,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 +391,7 @@ 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.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.15/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.15}/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.15}/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.15/codex_agent/cli/__init__.py

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

codex_agent_framework-0.1.15/codex_agent/cli/headless.py

@@ -0,0 +1,203 @@
+import json
+import sys
+import threading
+
+from .output import dump_ndjson, output_payload, key_value_text
+from .runner import in_process_runner, process_runner, server_runner
+
+
+TERMINAL_EVENTS = {"agent_turn_end_event", "agent_turn_error_event", "server_shutdown"}
+
+
+def runner_from_args(args):
+    runtime = getattr(args, "runtime", "server") or "server"
+    if runtime == "server":
+        return server_runner(base_url=args.url or f"http://{args.host}:{args.port}")
+    if runtime == "process":
+        from .main import default_agent_kwargs
+        return process_runner(agent_kwargs=default_agent_kwargs())
+    if runtime == "in-process":
+        from .main import default_agent
+        return in_process_runner(default_agent())
+    raise SystemExit(f"unsupported runtime: {runtime}")
+
+
+def should_stop_runner(args):
+    return (getattr(args, "runtime", "server") or "server") != "server"
+
+
+def output_format(args):
+    if getattr(args, "json", False):
+        return "json"
+    return getattr(args, "format", None) or "text"
+
+
+def read_prompt(args, extra_args):
+    if getattr(args, "stdin", False):
+        prompt = sys.stdin.read()
+    else:
+        prompt = " ".join(extra_args).strip()
+    if not prompt:
+        raise SystemExit("prompt is required; pass it as arguments or use --stdin")
+    return prompt
+
+
+def with_runner(args, callback):
+    runner = runner_from_args(args).start()
+    try:
+        return callback(runner)
+    finally:
+        if should_stop_runner(args):
+            runner.stop()
+
+
+def run_status(args, extra_args=None):
+    payload = with_runner(args, lambda runner: runner.get_status())
+    output_payload(payload, fmt=output_format(args), text_formatter=key_value_text)
+    return payload
+
+
+def run_tools(args, extra_args=None):
+    payload = with_runner(args, lambda runner: runner.tools())
+
+    def format_tools(data):
+        if isinstance(data, dict):
+            names = sorted(data.keys())
+        else:
+            names = [str(item) for item in data or []]
+        return "\n".join(names)
+
+    output_payload(payload, fmt=output_format(args), text_formatter=format_tools)
+    return payload
+
+
+def parse_config_value(value):
+    text = str(value)
+    lowered = text.lower()
+    if lowered == "true":
+        return True
+    if lowered == "false":
+        return False
+    if lowered == "null" or lowered == "none":
+        return None
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return value
+
+
+def parse_config_set_args(extra_args):
+    args = list(extra_args or [])
+    if not args:
+        raise SystemExit("config set requires KEY VALUE or KEY=VALUE")
+    values = {}
+    if len(args) == 1 and "=" in args[0]:
+        key, value = args[0].split("=", 1)
+        values[key] = parse_config_value(value)
+        return values
+    if len(args) % 2 != 0:
+        raise SystemExit("config set requires KEY VALUE pairs or KEY=VALUE")
+    for index in range(0, len(args), 2):
+        values[args[index]] = parse_config_value(args[index + 1])
+    return values
+
+
+def run_config(args, extra_args=None):
+    extra_args = list(extra_args or [])
+    command = extra_args[0] if extra_args else "get"
+    if command == "get":
+        payload = with_runner(args, lambda runner: runner.config())
+        if len(extra_args) >= 2:
+            key = extra_args[1]
+            payload = payload.get(key)
+    elif command == "set":
+        values = parse_config_set_args(extra_args[1:])
+        payload = with_runner(args, lambda runner: runner.update_config(values, save=not getattr(args, "no_save", False)))
+    else:
+        raise SystemExit(f"unsupported config command: {command}")
+    output_payload(payload, fmt=output_format(args), text_formatter=lambda data: key_value_text(data) if isinstance(data, dict) else str(data))
+    return payload
+
+
+def run_sessions(args, extra_args=None):
+    extra_args = list(extra_args or [])
+    command = extra_args[0] if extra_args else "list"
+
+    def action(runner):
+        if command == "list":
+            return runner.sessions()
+        if command == "new":
+            return runner.start_new_session()
+        if command == "load":
+            if len(extra_args) < 2:
+                raise SystemExit("sessions load requires a session id")
+            return runner.load_session(extra_args[1])
+        if command == "delete":
+            if len(extra_args) < 2:
+                raise SystemExit("sessions delete requires a session id")
+            return runner.delete_session(extra_args[1])
+        raise SystemExit(f"unsupported sessions command: {command}")
+
+    payload = with_runner(args, action)
+
+    def format_sessions(data):
+        if command != "list" or not isinstance(data, dict):
+            return key_value_text(data) if isinstance(data, dict) else str(data)
+        current = data.get("current")
+        sessions = data.get("sessions") or []
+        lines = []
+        for session in sessions:
+            session_id = session.get("id") if isinstance(session, dict) else str(session)
+            prefix = "*" if session_id == current else " "
+            title = session.get("title") or session.get("name") or "" if isinstance(session, dict) else ""
+            lines.append(f"{prefix} {session_id} {title}".rstrip())
+        return "\n".join(lines)
+
+    output_payload(payload, fmt=output_format(args), text_formatter=format_sessions)
+    return payload
+
+
+def run_interrupt(args, extra_args=None):
+    reason = " ".join(extra_args or []).strip() or "cli"
+    payload = with_runner(args, lambda runner: runner.interrupt(reason=reason))
+    output_payload(payload, fmt=output_format(args), text_formatter=key_value_text)
+    return payload
+
+
+def run_prompt(args, extra_args=None):
+    prompt = read_prompt(args, extra_args or [])
+    fmt = output_format(args)
+    runner = runner_from_args(args).start()
+    done = threading.Event()
+    result = {"ok": True, "text": "", "events": [], "accepted": None, "error": None}
+
+    def handle_event(event):
+        event_type = event.get("type")
+        if fmt == "ndjson":
+            dump_ndjson(event)
+        elif fmt == "text" and event_type == "response_content_delta_event":
+            delta = event.get("delta") or ""
+            result["text"] += delta
+            print(delta, end="", flush=True)
+        result["events"].append(dict(event))
+        if event_type == "agent_turn_error_event":
+            result["ok"] = False
+            result["error"] = event.get("error") or "agent turn failed"
+        if event_type in TERMINAL_EVENTS:
+            done.set()
+
+    runner.on_event(handle_event)
+    runner.start_events()
+    try:
+        accepted = runner.submit_prompt(prompt)
+        result["accepted"] = dict(accepted)
+        timeout = getattr(args, "wait_timeout", None)
+        if timeout != 0:
+            done.wait(timeout)
+        if fmt == "text" and result["text"]:
+            print()
+        if fmt == "json":
+            output_payload(result, fmt="json")
+        return result
+    finally:
+        runner.stop()