codex-agent-framework 0.1.52__tar.gz → 0.1.54__tar.gz

{codex_agent_framework-0.1.52 → codex_agent_framework-0.1.54}/CHANGELOG.md

@@ -4,6 +4,28 @@ 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.54] - 2026-05-17
+### Changed
+- Add a generic namespaced `/config` command surface so agent and plugin configs can be read, updated, and saved through a uniform dot-notation interface such as `/config agent.input_token_limit 200000`, `/config tts.voice nova`, `/config agent save`, and `/config save`.
+- Keep config persistence explicit for SDK-created agents while still materializing `agent.config.json` for long-lived server sessions at server bootstrap.
+- Simplify config loading by relying on direct `Config.load(...)` with ignored unknown extras instead of carrying legacy config shims.
+- Hide empty plugin config namespaces from `/config` output so only agent config and plugins with actual exposed config values are shown.
+- Align runtime/server/client paths and tests with the namespaced config model and the minimal default plugin surface.
+
+### Tests
+- Validate with targeted config/server/runtime coverage and the full suite at 611 passed.
+
+## [0.1.53] - 2026-05-16
+### Changed
+- Default new agents to a smaller built-in plugin surface: `files`, `environment`, `memory`, `planner`, `scheduler`, and `context`.
+- Persist `~/.codex-agent/agent.config.json` only on explicit save/update actions instead of automatically on agent initialization.
+- Make `web_search` and `image_generation` plugin-first server tools: loading the plugin now controls whether the corresponding Responses API tool is exposed.
+- Remove the redundant `web_search_enabled` and `image_generation_enabled` config flags from the public agent config surface.
+- Update docs and tests to reflect the minimal default plugin set and plugin-driven server tool activation.
+
+### Tests
+- Validate with targeted agent/plugin/image-generation coverage and a package build.
+
 ## [0.1.52] - 2026-05-16
 ### Changed
 - Document current synchronous Bash tool behavior and the planned direction for pollable, cancellable long-running shell jobs with durable logs and clear UI/API status.

{codex_agent_framework-0.1.52/codex_agent_framework.egg-info → codex_agent_framework-0.1.54}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-agent-framework
-Version: 0.1.52
+Version: 0.1.54
 Summary: A lightweight event-driven Codex agent runtime.
 Author: Baptiste
 License-Expression: MIT
@@ -188,7 +188,8 @@ agent = Agent(
 )
 ```
 
-`None` loads all built-ins, `[]` loads none, and an explicit list selects plugin module names.
+By default, the agent starts with a minimal built-in surface: `files`, `environment`, `memory`, `planner`, `scheduler`, and `context`.
+Pass `builtin_plugins=None` to load all built-ins, `[]` to load none, or an explicit list to select plugin module names.
 
 ## Project health
 

{codex_agent_framework-0.1.52 → codex_agent_framework-0.1.54}/README.md

@@ -139,7 +139,8 @@ agent = Agent(
 )
 ```
 
-`None` loads all built-ins, `[]` loads none, and an explicit list selects plugin module names.
+By default, the agent starts with a minimal built-in surface: `files`, `environment`, `memory`, `planner`, `scheduler`, and `context`.
+Pass `builtin_plugins=None` to load all built-ins, `[]` to load none, or an explicit list to select plugin module names.
 
 ## Project health
 

{codex_agent_framework-0.1.52 → codex_agent_framework-0.1.54}/codex_agent/agent_runtime.py

@@ -189,8 +189,8 @@ class InProcessAgentRuntime(AgentRuntime):
     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 update_config(self, values=None, save=True, namespace="agent", **kwargs):
+        return self.agent.config_manager.update_config(namespace, values, save=save, **kwargs)
 
     def session(self):
         return self.agent.session
@@ -588,11 +588,16 @@ class ProcessAgentRuntime(AgentRuntime):
     def config(self):
         return self._cached_call("config")
 
-    def update_config(self, values=None, save=True, **kwargs):
+    def update_config(self, values=None, save=True, namespace="agent", **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
+        result = self.call(
+            "update_config",
+            {"namespace": namespace, "values": payload, "save": save},
+            timeout=self.command_timeout,
+        )
+        if namespace == "agent":
+            self.cache["config"] = result
         return result
 
     def session(self):
@@ -703,6 +708,7 @@ class _RuntimeFuture:
 
 def agent_worker_main(command_queue, response_queue, event_queue, agent_kwargs):
     agent = Agent(**dict(agent_kwargs or {}))
+    agent.config_manager.save()
 
     def emit_event(event):
         event_queue.put(event_payload(event))
@@ -749,7 +755,11 @@ def run_worker_command(agent, name, payload):
     if name == "config":
         return agent.config
     if name == "update_config":
-        return agent.config_manager.update(payload.get("values") or {}, save=payload.get("save", True))
+        return agent.config_manager.update_config(
+            payload.get("namespace", "agent"),
+            payload.get("values") or {},
+            save=payload.get("save", True),
+        )
     if name == "session":
         return agent.session
     if name == "sessions":

codex_agent_framework-0.1.54/codex_agent/builtin_commands.py

@@ -0,0 +1,196 @@
+"""Built-in slash commands."""
+
+from modict import modict
+
+from .command import command
+from .config import parse_config_value
+from .sessions import AgentSession
+from .tool import get_agent
+
+
+def _format_lines(value, prefix=""):
+    if isinstance(value, dict):
+        lines = []
+        for key, child in value.items():
+            full_key = f"{prefix}.{key}" if prefix else str(key)
+            if isinstance(child, dict):
+                lines.append(f"{full_key}:")
+                lines.extend(_format_lines(child, full_key))
+            else:
+                lines.append(f"{full_key}: {child!r}")
+        return lines
+    return [f"{prefix}: {value!r}" if prefix else repr(value)]
+
+
+def format_config_output(value, prefix=""):
+    return "\n".join(_format_lines(value, prefix=prefix)) if isinstance(value, dict) else repr(value)
+
+
+@command
+def help():
+    agent = get_agent()
+    names = ", ".join(f"/{name}" for name in sorted(agent.commands))
+    return f"Available commands: {names}"
+
+
+@command
+def compact(max_compacted_turns=None):
+    agent = get_agent()
+    max_compacted_turns = None if max_compacted_turns in (None, "", "all") else int(max_compacted_turns)
+    message = agent.compact_session(
+        model=agent.config.model,
+        instructions=agent.config_manager.system_message().content,
+        max_compacted_turns=max_compacted_turns,
+    )
+    if message is None:
+        return "Nothing to compact."
+    if message.get("status") == "failed":
+        return f"Compaction failed: {message.error}"
+    suffix = "" if max_compacted_turns is None else f" from {max_compacted_turns} compacted turn(s)"
+    return f"Compacted {message.compacted_message_count} messages{suffix}."
+
+
+def _message_count_text(count):
+    return f"{count} message" if count == 1 else f"{count} messages"
+
+
+def _session_infos(agent):
+    infos = []
+    for index, info in enumerate(AgentSession.list_session_infos(), start=1):
+        infos.append(modict(
+            index=index,
+            session_id=info.session_id,
+            title=info.title or info.session_id,
+            message_count=info.message_count,
+            current=info.session_id == agent.current_session_id,
+        ))
+    return infos
+
+
+def _format_session_list(agent):
+    infos = _session_infos(agent)
+    if not infos:
+        return "No saved sessions."
+    lines = ["Sessions:"]
+    for info in infos:
+        marker = "*" if info.current else " "
+        lines.append(
+            f"{marker} [{info.index}] {info.title} "
+            f"({info.session_id}, {_message_count_text(info.message_count)})"
+        )
+    return "\n".join(lines)
+
+
+@command
+def session(action=None, *parts):
+    agent = get_agent()
+    if action is None:
+        return _format_session_list(agent)
+
+    action_text = str(action).strip()
+    action_lower = action_text.lower()
+    if action_lower == "new":
+        created = agent.start_new_session()
+        return f"Created session: {created.session_id}"
+
+    if action_lower == "rename":
+        title = " ".join(str(part) for part in parts).strip()
+        if not title:
+            raise ValueError("/session rename requires a title")
+        if agent.session is None:
+            raise ValueError("No active session to rename")
+        agent.session.title = title
+        agent.save_session()
+        return f"Renamed session: {title}"
+
+    if parts:
+        raise ValueError("Usage: /session, /session <index>, /session new, /session rename <title>")
+
+    try:
+        index = int(action_text)
+    except ValueError as exc:
+        raise ValueError(f"Unknown /session action: {action_text}") from exc
+
+    infos = _session_infos(agent)
+    if index < 1 or index > len(infos):
+        raise ValueError(f"Session index out of range: {index}")
+    loaded = agent.load_session(infos[index - 1].session_id)
+    return f"Loaded session: {loaded.session_id}"
+
+
+@command
+def config(path=None, value=None, *extra, **values):
+    agent = get_agent()
+    manager = agent.config_manager
+
+    if values:
+        unknown = sorted(key for key in values if key not in agent.config)
+        if unknown:
+            raise ValueError(f"Unknown model config keys: {', '.join(unknown)}")
+        parsed = {key: parse_config_value(raw) for key, raw in values.items()}
+        manager.update_config("agent", config=parsed, save=True)
+        changed = ", ".join(f"{key}={agent.config.get(key)!r}" for key in parsed)
+        return f"Updated config: {changed}" if changed else format_config_output(manager.export_tree())
+
+    if path is None:
+        if value is not None or extra:
+            raise ValueError("/config with no path does not accept extra arguments")
+        return format_config_output(manager.export_tree())
+
+    if path == "save":
+        manager.save_all()
+        return "Saved all config namespaces."
+
+    if value is None and not extra:
+        displayed = manager.get_path(path)
+        return format_config_output(displayed, prefix=path)
+
+    if value == "save" and not extra:
+        namespace, remainder = manager.namespace_path(path)
+        if remainder:
+            raise ValueError("Save targets a config namespace, not a nested key")
+        manager.save_config(namespace)
+        return f"Saved config namespace: {namespace}"
+
+    raw_value = " ".join(str(part) for part in ((value,) + extra))
+    updated = manager.set_path(path, raw_value, save=False)
+    return f"Updated config: {path}={updated!r}"
+
+
+@command
+def model(value=None):
+    if value is None:
+        return f"model: {get_agent().config.model!r}"
+    get_agent().config_manager.set_path("agent.model", value, save=True)
+    return f"Updated config: model={get_agent().config.model!r}"
+
+
+@command
+def reasoning(value=None):
+    agent = get_agent()
+    if value is None:
+        return f"reasoning: {agent.config.get('reasoning')!r}"
+    current = dict(agent.config.get("reasoning") or {})
+    current["effort"] = value
+    current.setdefault("summary", "auto")
+    agent.config_manager.update_config("agent", reasoning=current, save=True)
+    return f"Updated config: reasoning={agent.config.get('reasoning')!r}"
+
+
+@command
+def verbosity(value=None):
+    agent = get_agent()
+    if value is None:
+        return f"text: {agent.config.get('text')!r}"
+    current = dict(agent.config.get("text") or {})
+    current["verbosity"] = value
+    agent.config_manager.update_config("agent", text=current, save=True)
+    return f"Updated config: text={agent.config.get('text')!r}"
+
+
+@command
+def voice(value=None):
+    agent = get_agent()
+    if "tts" not in agent.plugins:
+        agent.load_builtin_plugin("tts")
+    return agent.plugins.tts.voice(value)

codex_agent_framework-0.1.54/codex_agent/builtin_plugins/web_search/__init__.py

@@ -0,0 +1,11 @@
+from ...plugin import Plugin
+from ...tool import WebSearchTool
+
+
+class WebSearchPlugin(Plugin):
+    name = "web_search"
+    description = "OpenAI Responses API web search server tool."
+
+    def __init__(self, agent):
+        super().__init__(agent)
+        self.agent.tools_manager.add_server_tool(WebSearchTool())

{codex_agent_framework-0.1.52 → codex_agent_framework-0.1.54}/codex_agent/client.py

@@ -327,10 +327,10 @@ class AgentClient:
     def get_config(self):
         return self.get("/config")
 
-    def update_config(self, values=None, save=True, **kwargs):
+    def update_config(self, values=None, save=True, namespace="agent", **kwargs):
         payload = dict(values or {})
         payload.update(kwargs)
-        return self.request("PATCH", "/config", json={"values": payload, "save": save})
+        return self.request("PATCH", "/config", json={"values": payload, "save": save, "namespace": namespace})
 
     def tools(self):
         return self.get("/tools")

{codex_agent_framework-0.1.52 → codex_agent_framework-0.1.54}/codex_agent/config.py

@@ -1,7 +1,9 @@
+import json
 import os
 import platform
 
 from modict import modict
+from modict.collections_utils import get_nested
 
 from .event import RuntimeStateChangedEvent
 from .message import SystemMessage
@@ -12,8 +14,71 @@ DEFAULT_SYSTEM_PROMPT_PATH = os.path.join(os.path.dirname(__file__), "prompts",
 DEFAULT_SYSTEM_PROMPT = text_content(DEFAULT_SYSTEM_PROMPT_PATH)
 
 
-class AgentConfig(modict):
-    _config = modict.config(enforce_json=True)
+def parse_config_value(value):
+    if isinstance(value, bool):
+        return value
+    if not isinstance(value, str):
+        return value
+
+    lowered = value.lower()
+    if lowered in ("true", "yes", "on", "1"):
+        return True
+    if lowered in ("false", "no", "off", "0"):
+        return False
+    if lowered in ("none", "null"):
+        return None
+    if value.isdigit() or (value.startswith("-") and value[1:].isdigit()):
+        return int(value)
+    try:
+        if any(char in value for char in (".", "e", "E")):
+            return float(value)
+    except ValueError:
+        pass
+    if (value.startswith("{") and value.endswith("}")) or (value.startswith("[") and value.endswith("]")):
+        return json.loads(value)
+    return value
+
+
+class Config(modict):
+    _config = modict.config(enforce_json=True, extra="ignore", validate_default=True)
+
+    def save(self, file_path):
+        target = str(file_path)
+        if not target:
+            raise ValueError(f"No file path configured for {type(self).__name__}")
+        parent = os.path.dirname(target)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        self.dump(target, indent=2, ensure_ascii=False)
+        return self
+
+    def set_path(self, path, raw_value):
+        path = str(path or "").strip()
+        value = parse_config_value(raw_value)
+        if not path:
+            if not isinstance(value, dict):
+                raise ValueError("Root config assignment expects a mapping value")
+            self.clear()
+            self.update(value)
+            return self
+        if "." not in path:
+            self[path] = value
+            return self[path]
+        parent_path, _, leaf = path.rpartition(".")
+        parent = get_nested(self, parent_path)
+        if not isinstance(parent, dict):
+            raise TypeError(f"Config path {path!r} does not resolve to a mapping parent")
+        parent[leaf] = value
+        return get_nested(self, path)
+
+    def get_path(self, path=None, default=None):
+        path = str(path or "").strip()
+        if not path:
+            return self
+        return get_nested(self, path, default=default)
+
+
+class AgentConfig(Config):
 
     model = "gpt-5.4"
     system = DEFAULT_SYSTEM_PROMPT
@@ -35,14 +100,12 @@ class AgentConfig(modict):
     vision_enabled = True
     max_images = 10
     prune_orphaned_tool_outputs_on_context_build = True
-    web_search_enabled = False
-    image_generation_enabled = False
     image_generation_output_format = "png"
     image_generation_size = None
     image_generation_quality = None
     image_generation_background = None
     image_generation_moderation = None
-    builtin_plugins = None
+    builtin_plugins = ["files", "environment", "memory", "planner", "scheduler", "context"]
     custom_plugins = None
     exclude_tools = modict.factory(list)
     server_url = "http://127.0.0.1:8765"
@@ -67,8 +130,9 @@ class AgentConfig(modict):
         )
 
 
-class PluginConfig(modict):
-    _config = modict.config(enforce_json=True)
+
+class PluginConfig(Config):
+    _config = modict.config(enforce_json=True, extra="allow", validate_default=True)
 
 
 def _as_name_set(value):
@@ -94,10 +158,6 @@ class ConfigManager:
     def file(self):
         return runtime_join("agent.config.json")
 
-    @property
-    def legacy_file(self):
-        return runtime_join("agent_config.json")
-
     def config_file(self, namespace="agent", file=None):
         if file is not None:
             return str(file)
@@ -108,13 +168,22 @@ class ConfigManager:
     def save(self):
         return self.save_config("agent")
 
+    def save_all(self):
+        if self.should_queue_state_command():
+            return self.agent.submit("save_config", namespace=None).wait().result
+        saved = modict()
+        for namespace in list(self.configs):
+            saved[namespace] = self.save_config(namespace)
+        return saved
+
     def save_config(self, namespace="agent"):
-        if namespace == "agent" and self.should_queue_state_command():
-            return self.agent.submit("save_config").wait().result
-        config = self.configs.get(namespace)
-        if config is None:
-            raise KeyError(f"Unknown config namespace: {namespace}")
+        if self.should_queue_state_command():
+            return self.agent.submit("save_config", namespace=namespace).wait().result
+        config = self.get_config(namespace)
         file = self.config_files.get(namespace) or self.config_file(namespace)
+        self.config_files[namespace] = file
+        if isinstance(config, Config):
+            return config.save(file)
         parent = os.path.dirname(file)
         if parent:
             os.makedirs(parent, exist_ok=True)
@@ -122,9 +191,8 @@ class ConfigManager:
         return config
 
     def load(self):
-        source = self.file if os.path.isfile(self.file) else self.legacy_file
-        if os.path.isfile(source):
-            self.config = AgentConfig.load(source)
+        if os.path.isfile(self.file):
+            self.config = AgentConfig.load(self.file)
             self.agent.config = self.config
         self.configs.agent = self.config
         self.config_files.agent = self.file
@@ -144,38 +212,24 @@ class ConfigManager:
         return config
 
     def update(self, config=None, save=True, **kwargs):
+        return self.update_config("agent", config=config, save=save, **kwargs)
+
+    def update_config(self, namespace="agent", config=None, save=True, **kwargs):
         if self.should_queue_state_command():
             return self.agent.submit(
                 "update_config",
+                namespace=namespace,
                 config=config,
                 save=save,
                 kwargs=kwargs,
             ).wait().result
-        data = modict(config or {})
-        data.update(kwargs)
-        if data:
-            self.config.update(data)
-            self.agent.config = self.config
-            if save:
-                self.save()
-            self.emit_state_changed(
-                reason="config_updated",
-                namespace="config",
-                name="agent",
-                details=data,
-            )
-        return self.config
-
-    def update_config(self, namespace="agent", config=None, save=True, **kwargs):
-        if namespace == "agent":
-            return self.update(config, save=save, **kwargs)
-        target = self.configs.get(namespace)
-        if target is None:
-            raise KeyError(f"Unknown config namespace: {namespace}")
+        target = self.get_config(namespace)
         data = modict(config or {})
         data.update(kwargs)
         if data:
             target.update(data)
+            if namespace == "agent":
+                self.agent.config = target
             if save:
                 self.save_config(namespace)
             self.emit_state_changed(
@@ -186,6 +240,67 @@ class ConfigManager:
             )
         return target
 
+    def get_config(self, namespace="agent"):
+        target = self.configs.get(str(namespace))
+        if target is None:
+            raise KeyError(f"Unknown config namespace: {namespace}")
+        return target
+
+    def namespace_path(self, path=None):
+        text = str(path or "").strip()
+        if not text:
+            return None, ""
+        namespace, _, remainder = text.partition(".")
+        if namespace not in self.configs:
+            raise KeyError(f"Unknown config namespace: {namespace}")
+        return namespace, remainder
+
+    def get_path(self, path=None, default=None):
+        if not path:
+            return modict({namespace: config for namespace, config in self.configs.items()})
+        namespace, remainder = self.namespace_path(path)
+        target = self.get_config(namespace)
+        return target.get_path(remainder, default=default) if isinstance(target, Config) else get_nested(target, remainder, default=default)
+
+    def set_path(self, path, raw_value, *, save=False):
+        namespace, remainder = self.namespace_path(path)
+        target = self.get_config(namespace)
+        if isinstance(target, Config):
+            result = target.set_path(remainder, raw_value)
+        else:
+            parsed = parse_config_value(raw_value)
+            if not remainder:
+                if not isinstance(parsed, dict):
+                    raise ValueError("Root config assignment expects a mapping value")
+                target.clear()
+                target.update(parsed)
+                result = target
+            else:
+                parent_path, _, leaf = remainder.rpartition(".")
+                parent = target if not parent_path else get_nested(target, parent_path)
+                if not isinstance(parent, dict):
+                    raise TypeError(f"Config path {path!r} does not resolve to a mapping parent")
+                parent[leaf] = parsed
+                result = get_nested(target, remainder)
+        if namespace == "agent":
+            self.agent.config = self.config
+        if save:
+            self.save_config(namespace)
+        self.emit_state_changed(
+            reason="config_updated",
+            namespace="config",
+            name=namespace,
+            details=modict(path=path, value=self.get_path(path)),
+        )
+        return result
+
+    def export_tree(self):
+        return modict({
+            namespace: config
+            for namespace, config in self.configs.items()
+            if namespace == "agent" or bool(config)
+        })
+
     def emit_state_changed(self, **data):
         if hasattr(self.agent, "events"):
             self.agent.emit(RuntimeStateChangedEvent, **data)
@@ -223,22 +338,6 @@ class ConfigManager:
             self.config.pop(key, None)
         return self.config
 
-    def pop_legacy_section(self, section):
-        parts = str(section).split(".")
-        parent = self.config
-        for part in parts[:-1]:
-            parent = parent.get(part) if isinstance(parent, dict) else None
-            if parent is None:
-                return None
-        if isinstance(parent, dict):
-            return parent.pop(parts[-1], None)
-        return None
-
-    def prune_empty_legacy_containers(self):
-        plugins = self.config.get("plugins")
-        if isinstance(plugins, dict) and not plugins:
-            self.config.pop("plugins", None)
-
     def apply_config_defaults(
         self,
         namespace,
@@ -250,21 +349,7 @@ class ConfigManager:
         legacy_agent_sections=None,
     ):
         config = self.load_config(namespace, config_class=config_class, file=file, defaults=defaults)
-        migrated = False
-        for section in legacy_agent_sections or ():
-            legacy = self.pop_legacy_section(section)
-            if isinstance(legacy, dict):
-                config.update(legacy)
-                migrated = True
-        for legacy_key, plugin_key in (legacy_agent_aliases or {}).items():
-            if legacy_key in self.config:
-                config[plugin_key] = self.config.pop(legacy_key)
-                migrated = True
-        self.prune_empty_legacy_containers()
         self.agent.config = self.config
-        if migrated:
-            self.save_config(namespace)
-            self.save()
         return config
 
     def system_message(self):

{codex_agent_framework-0.1.52 → codex_agent_framework-0.1.54}/codex_agent/mainloop.py

@@ -263,13 +263,15 @@ class MainLoopManager:
         if command.name == "navigate_session":
             return self.agent.navigate_session(command.payload.direction)
         if command.name == "update_config":
-            return self.agent.config_manager.update(
+            return self.agent.config_manager.update_config(
+                command.payload.get("namespace", "agent"),
                 command.payload.get("config"),
                 save=command.payload.get("save", True),
                 **command.payload.get("kwargs", {}),
             )
         if command.name == "save_config":
-            return self.agent.config_manager.save()
+            namespace = command.payload.get("namespace", "agent")
+            return self.agent.config_manager.save_all() if namespace is None else self.agent.config_manager.save_config(namespace)
         if command.name == "save_session":
             return self.agent.save_session()
         if command.name == "compact_session":