optio-codex 0.1.0__tar.gz → 0.2.1__tar.gz

{optio_codex-0.1.0 → optio_codex-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optio-codex
-Version: 0.1.0
+Version: 0.2.1
 Summary: Run OpenAI Codex as an optio task; local subprocess; ttyd-served TUI iframe.
 Author-email: Kristof Csillag <kristof.csillag@deai-labs.com>
 License-Expression: Apache-2.0
@@ -22,12 +22,13 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 Requires-Dist: optio-core<0.4,>=0.3
 Requires-Dist: optio-host<0.3,>=0.2
-Requires-Dist: optio-agents<0.4,>=0.3
+Requires-Dist: optio-agents<0.5,>=0.4
 Requires-Dist: asyncssh>=2.14
 Requires-Dist: aiohttp>=3.9
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-xdist>=3.6; extra == "dev"
 
 # optio-codex
 

{optio_codex-0.1.0 → optio_codex-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "optio-codex"
-version = "0.1.0"
+version = "0.2.1"
 description = "Run OpenAI Codex as an optio task; local subprocess; ttyd-served TUI iframe."
 readme = "README.md"
 license = "Apache-2.0"
@@ -28,7 +28,7 @@ classifiers = [
 dependencies = [
     "optio-core>=0.3,<0.4",
     "optio-host>=0.2,<0.3",
-    "optio-agents>=0.3,<0.4",
+    "optio-agents>=0.4,<0.5",
     "asyncssh>=2.14",
     "aiohttp>=3.9",
 ]
@@ -37,6 +37,7 @@ dependencies = [
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.23",
+    "pytest-xdist>=3.6",
 ]
 
 [project.urls]

{optio_codex-0.1.0 → optio_codex-0.2.1}/src/optio_codex/__init__.py

@@ -9,6 +9,7 @@ from optio_host import (
     SSHConfig,
 )
 
+from optio_codex.info import AGENT_INFO
 from optio_codex.seed_manifest import (
     CODEX_CRED_MANIFEST,
     CODEX_SEED_MANIFEST,
@@ -38,6 +39,7 @@ _logging.getLogger("asyncssh").setLevel(_logging.WARNING)
 
 
 __all__ = [
+    "AGENT_INFO",
     "create_codex_task",
     "run_codex_session",
     "AllowedDir",

{optio_codex-0.1.0 → optio_codex-0.2.1}/src/optio_codex/conversation.py

@@ -53,7 +53,7 @@ Client -> server REQUESTS (have ``id``, expect a ``result``):
     IMMEDIATE ACK {turn:{id, status:"inProgress", items:[]}} — the ACK is
     NOT the turn end. Per-turn overrides (``model``) become the default for
     subsequent turns on the thread == the INLINE model-switch seam
-    (request_model_change pins the next turn's model; no wire write).
+    (set_control("model", …) pins the next turn's model; no wire write).
   * ``turn/interrupt`` {threadId, turnId} -> {} ACK; the completion signal
     is the subsequent ``turn/completed`` with status "interrupted".
 
@@ -100,6 +100,8 @@ from optio_agents.conversation import (
     PermissionDecision,
     PermissionRequest,
 )
+from optio_codex import models as codex_models
+from optio_codex.info import AGENT_INFO
 
 _LOG = logging.getLogger(__name__)
 
@@ -119,9 +121,10 @@ class CodexConversation:
         self,
         *,
         cwd: str,
-        agent_label: str = "codex",
+        agent_label: str = AGENT_INFO.slug,
         permission_gate: bool = False,
         model: str | None = None,
+        reasoning_effort: str | None = None,
         sandbox: str = "workspace-write",
         resume_thread_id: str | None = None,
     ) -> None:
@@ -135,6 +138,11 @@ class CodexConversation:
         # With the gate on codex must ask (on-request); without it, never.
         self._approval_policy = "on-request" if permission_gate else "never"
         self._resume_thread_id = resume_thread_id
+        # Prior conversation captured at bootstrap when resuming: thread/resume
+        # returns the whole thing inline as thread.turns[].items[] (verified
+        # live). Stashed here (bootstrap runs before any listener subscribes) so
+        # replay_history can backfill it into on_event once the listener is up.
+        self._resume_turns: list = []
         self._handle = None
         # Captured at bootstrap; Plan B's snapshot sessionId seam reads
         # thread_id at capture time.
@@ -147,6 +155,12 @@ class CodexConversation:
         self.model_list: dict | None = None
         self.current_model_id: str | None = None
         self._requested_model: str | None = None
+        # Graded reasoning effort armed for the next turn/start (codex's
+        # per-turn `effort` override; None → codex uses the model default).
+        # Seeded from config at launch (initial effort, like model), updated
+        # INLINE by set_control("reasoning_effort", …), and reconciled to a
+        # valid value / dropped when the model changes.
+        self._requested_effort: str | None = reasoning_effort
         self._pending = 0                    # user turns awaiting turn/completed
         self._closed = asyncio.Event()
         self._close_reason: str | None = None
@@ -240,6 +254,57 @@ class CodexConversation:
                 f"codex {method} returned no thread id: {result!r}"
             )
         self.current_model_id = result.get("model") or self._model
+        # thread/resume returns the FULL prior conversation inline as
+        # thread.turns[].items[] (verified live); stash it for replay_history to
+        # backfill into on_event after the listener subscribes. thread/start has
+        # no prior turns → [].
+        self._resume_turns = thread.get("turns") or []
+
+    async def replay_history(self) -> int:
+        """Backfill on_event with the RESUMED thread's prior turns.
+
+        On resume, thread/resume returned the whole prior conversation inline as
+        result.thread.turns[].items[], which bootstrap stashed — but the
+        listener's replay buffer starts empty and only accrues LIVE turns, so a
+        viewer attaching after a resume would see none of the prior conversation.
+        So re-emit each stored item as the ``item/completed`` notification the
+        live stream would have sent for it, plus a ``turn/completed`` after each
+        turn, through the SAME on_event fan-out live items use — landing them in
+        the listener's buffer so a late viewer reconstructs the full prior
+        history, each item rendered identically to a live one (the UI reducer
+        treats a replayed item/completed exactly like a streamed one — its
+        untracked-completion branch IS the replay-gap path; the per-turn
+        turn/completed closes each turn's answer bubble and opens the next).
+
+        Drives ONLY on_event — no answer accumulation, no on_message: a resume
+        must not synthesise a phantom answer turn (mirrors optio-antigravity's
+        replay_history). Safe with no history (thread/start, or a resume with no
+        prior turns): emits nothing, returns 0. Returns the number of events
+        emitted.
+        """
+        count = 0
+        for turn in self._resume_turns:
+            turn_id = turn.get("id")
+            for item in turn.get("items") or []:
+                await self._emit_event({"method": "item/completed", "params": {
+                    "threadId": self.thread_id, "turnId": turn_id, "item": item}})
+                count += 1
+            # Close this historic turn's bubble and open the next's — a live
+            # multi-turn stream ends every turn with turn/completed, so replay
+            # must too (else the reducer coalesces all turns into one bubble).
+            await self._emit_event({"method": "turn/completed", "params": {
+                "threadId": self.thread_id,
+                "turn": {"id": turn_id, "status": "completed"}}})
+            count += 1
+        return count
+
+    async def _emit_event(self, obj: dict) -> None:
+        """Fan one event out to on_event subscribers directly — the tail of the
+        live _event_queue -> _dispatch_loop -> _event_handlers path, reused by
+        the resume-history backfill (which must NOT touch turn/answer state, so
+        it bypasses _route/_on_notification and the on_message coalescer)."""
+        for handler in list(self._event_handlers):
+            await self._call_handler(handler, obj, "on_event")
 
     async def run_reader(self) -> None:
         """Drain stdout until EOF; route JSON-RPC messages. Owned by the
@@ -432,6 +497,11 @@ class CodexConversation:
             # Inline model switch: the override becomes the thread default
             # for subsequent turns (app-server contract).
             params["model"] = self._requested_model
+        if self._requested_effort is not None:
+            # Inline graded-reasoning override: `effort` rides each turn/start
+            # (the app-server has no dedicated set-effort request). Seeded from
+            # config at launch, then moved by the reasoning_effort slider.
+            params["effort"] = self._requested_effort
         try:
             await self._write_json({
                 "id": rid, "method": "turn/start", "params": params,
@@ -482,19 +552,51 @@ class CodexConversation:
             "threadId": self.thread_id, "turnId": self.current_turn_id,
         })
 
-    def request_model_change(self, model: str) -> None:
-        """Switch model mid-conversation INLINE — with NO wire write: a
-        ``model`` override on the next ``turn/start`` becomes the thread's
-        default for subsequent turns (app-server contract; see models.py).
-        Synchronous surface (the listener calls it without await)."""
+    async def set_control(self, control_id: str, value) -> None:
+        """Push a session-control value change to the native transport
+        (generalizes model selection). Codex exposes two controls, both
+        switched INLINE with NO dedicated wire write — a ``model`` / ``effort``
+        override on the next ``turn/start`` becomes the thread default for
+        subsequent turns (app-server contract; see models.py):
+
+        * ``model`` — pins the model on the next turn. Because graded-reasoning
+          support is model-dependent, a model switch RE-DERIVES the control set
+          for the new model and re-emits it as an ``x-optio-control-update`` so
+          the effort slider appears / disappears / relevels to follow the model
+          (reconciling the armed effort to a value the new model supports, or
+          dropping it when the new model has no graded reasoning).
+        * ``reasoning_effort`` — arms ``effort`` for the next turn (the client
+          folds the slider value optimistically; no re-emit needed).
+
+        Unknown control ids are ignored (no-op)."""
+        if control_id not in ("model", "reasoning_effort"):
+            return  # codex exposes only the model + reasoning_effort controls
         if self._closed.is_set():
             raise ConversationClosed(self._close_reason or "conversation closed")
         if self.thread_id is None:
             raise RuntimeError(
-                "CodexConversation.request_model_change before bootstrap() completed"
+                "CodexConversation.set_control before bootstrap() completed"
             )
-        self._requested_model = model
-        self.current_model_id = model  # optimistic; the next turn pins it
+        if control_id == "reasoning_effort":
+            self._requested_effort = value  # armed for the next turn/start
+            return
+        # control_id == "model": inline switch + reconcile effort to the new
+        # model, then re-emit the re-derived control set.
+        self._requested_model = value
+        self.current_model_id = value  # optimistic; the next turn pins it
+        model_list = codex_models.parse_model_list(self.model_list)
+        levels, default = codex_models.effort_for_model(model_list, value)
+        if self._requested_effort is not None and self._requested_effort not in levels:
+            # The armed effort is invalid for the new model: fall back to the
+            # new model's default (still graded) or drop it (no graded effort).
+            self._requested_effort = default if levels else None
+        controls = codex_models.build_controls(
+            model_list, value, self._requested_effort,
+        )
+        await self._emit_event({
+            "type": "x-optio-control-update",
+            "controls": [c.to_dict() for c in controls],
+        })
 
     async def close(self) -> None:
         self.close_requested.set()

{optio_codex-0.1.0 → optio_codex-0.2.1}/src/optio_codex/conversation_listener.py

@@ -7,10 +7,8 @@ widget proxy (which injects the basic-auth credential):
                      monotonic seq; Last-Event-ID resumes without dupes.
   POST /send       — {text}                 -> conversation.send
   POST /interrupt  — {}                     -> conversation.interrupt
-  POST /model      — {model}                -> conversation.request_model_change
-                     (INLINE: pins the next turn/start's model — no restart)
-  POST /upload     — multipart {file} parts -> upload_writer; returns
-                     {ok, files:[{filename, path}]}
+  POST /control    — {id, value}            -> conversation.set_control
+                     (model: INLINE — pins the next turn/start's model, no restart)
   GET  /download   — ?path=<relpath>        -> download_reader; returns the
                      bytes with Content-Disposition: attachment
   POST /permission — {request_id, behavior, updated_input?, message?}
@@ -53,15 +51,11 @@ _STOP = object()
 class ConversationListener:
     def __init__(
         self, conversation, *, password: str,
-        upload_writer: "Callable[[str, bytes], Awaitable[str]] | None" = None,
-        max_upload_bytes: int = 10_000_000,
         download_reader: "Callable[[str], Awaitable[tuple[bytes, str]]] | None" = None,
         max_download_bytes: int = 10_000_000,
     ) -> None:
         self._conversation = conversation
         self._password = password
-        self._upload_writer = upload_writer
-        self._max_upload_bytes = max_upload_bytes
         self._download_reader = download_reader
         self._max_download_bytes = max_download_bytes
         self._buffer: deque[tuple[int, dict]] = deque(maxlen=BUFFER_MAXLEN)
@@ -192,35 +186,6 @@ class ConversationListener:
             return web.json_response({"ok": False, "reason": "closed"}, status=409)
         return web.json_response({"ok": True})
 
-    async def _handle_upload(self, request: web.Request) -> web.Response:
-        if not self._authorized(request):
-            return web.json_response({"ok": False}, status=401)
-        if self._upload_writer is None:
-            return web.json_response({"ok": False, "reason": "no-writer"}, status=409)
-        stored: list[dict] = []
-        try:
-            reader = await request.multipart()
-        except Exception:  # noqa: BLE001
-            return web.json_response({"ok": False, "reason": "bad-multipart"}, status=400)
-        while True:
-            part = await reader.next()
-            if part is None:
-                break
-            if part.name != "file":
-                continue
-            filename = part.filename or "file"
-            buf = bytearray()
-            while True:
-                chunk = await part.read_chunk()
-                if not chunk:
-                    break
-                buf.extend(chunk)
-                if len(buf) > self._max_upload_bytes:
-                    return web.json_response({"ok": False, "reason": "too-large"}, status=413)
-            path = await self._upload_writer(filename, bytes(buf))
-            stored.append({"filename": filename, "path": path})
-        return web.json_response({"ok": True, "files": stored})
-
     async def _handle_download(self, request: web.Request) -> web.Response:
         if not self._authorized(request):
             return web.json_response({"ok": False}, status=401)
@@ -246,18 +211,19 @@ class ConversationListener:
             },
         )
 
-    async def _handle_model(self, request: web.Request) -> web.Response:
+    async def _handle_control(self, request: web.Request) -> web.Response:
         if not self._authorized(request):
             return web.json_response({"ok": False}, status=401)
         try:
             payload = await request.json()
         except Exception:  # noqa: BLE001
             return web.json_response({"ok": False, "reason": "bad-json"}, status=400)
-        model = payload.get("model")
-        if not isinstance(model, str) or not model:
-            return web.json_response({"ok": False, "reason": "bad-model"}, status=400)
+        cid = payload.get("id")
+        if not isinstance(cid, str) or not cid:
+            return web.json_response({"ok": False, "reason": "bad-id"}, status=400)
+        value = payload.get("value")
         try:
-            self._conversation.request_model_change(model)
+            await self._conversation.set_control(cid, value)
         except ConversationClosed:
             return web.json_response({"ok": False, "reason": "closed"}, status=409)
         return web.json_response({"ok": True})
@@ -290,8 +256,7 @@ class ConversationListener:
         app.router.add_get("/events", self._handle_events)
         app.router.add_post("/send", self._handle_send)
         app.router.add_post("/interrupt", self._handle_interrupt)
-        app.router.add_post("/model", self._handle_model)
-        app.router.add_post("/upload", self._handle_upload)
+        app.router.add_post("/control", self._handle_control)
         app.router.add_get("/download", self._handle_download)
         app.router.add_post("/permission", self._handle_permission)
         self._runner = web.AppRunner(app, shutdown_timeout=SHUTDOWN_TIMEOUT_S)

{optio_codex-0.1.0 → optio_codex-0.2.1}/src/optio_codex/fs_allowlist.py

@@ -89,16 +89,17 @@ def resolve_sandbox_settings(
     """Resolve ``fs_isolation``/``sandbox``/``extra_allowed_dirs``/
     ``network_access`` into one :class:`SandboxSettings`.
 
-    ``ro`` grants are skipped (codex never restricts reads — see module
-    docstring); ``rw`` grants become ``writable_roots`` with ``~/`` expanded
-    against ``host_home``. Roots/network only apply to workspace-write
-    (validated in CodexTaskConfig.__post_init__).
+    ``ro``/``rox`` grants are skipped (codex never restricts reads — see module
+    docstring); ``rw``/``rwx`` grants become ``writable_roots`` with ``~/``
+    expanded against ``host_home`` (codex's native sandbox has no execute bit,
+    so ``rwx``==``rw`` and ``rox``==``ro``). Roots/network only apply to
+    workspace-write (validated in CodexTaskConfig.__post_init__).
     """
     mode = config.effective_sandbox_mode
     roots: list[str] = []
     if mode == "workspace-write":
         for ad in config.extra_allowed_dirs or []:
-            if ad.mode == "rw":
+            if ad.mode in ("rw", "rwx"):
                 roots.append(_expand_home(ad.path, host_home).rstrip("/"))
     return SandboxSettings(
         mode=mode,

{optio_codex-0.1.0 → optio_codex-0.2.1}/src/optio_codex/host_actions.py

@@ -13,6 +13,7 @@ from datetime import datetime, timezone
 from typing import TYPE_CHECKING
 
 from optio_agents import RESUME_NOTICE, SYSTEM_MESSAGE_PREFIX
+from optio_agents import tmux_input as _tmux_input
 from optio_host.host import proc_wait
 
 if TYPE_CHECKING:
@@ -104,7 +105,7 @@ async def resolve_codex(
             return candidate
         raise RuntimeError(
             f"codex not present at {candidate!r} on host "
-            f"(codex_install_dir={install_dir!r})."
+            f"(install_dir={install_dir!r})."
         )
 
     result = await host.run_command("bash -lc 'command -v codex'")
@@ -127,7 +128,7 @@ async def _resolve_codex_cache_dir(host: "Host", override: str | None) -> str:
     """Resolve the optio-owned codex binary-cache dir as an absolute worker
     path.
 
-    ``override`` (``config.codex_install_dir``) wins. Otherwise the worker's
+    ``override`` (``config.install_dir``) wins. Otherwise the worker's
     real env decides via a shell echo: ``OPTIO_CODEX_CACHE_DIR`` else
     ``${XDG_CACHE_HOME:-$HOME/.cache}/optio-codex/bin`` — resolved on the
     host so RemoteHost gets the remote location. Mirrors grok's
@@ -953,22 +954,25 @@ async def tmux_session_alive(
 async def send_text_to_codex(
     host: "Host", tmux_path: str, tmux_socket: str, tmux_session: str, text: str,
 ) -> None:
-    s = shlex.quote(tmux_socket)
-    sess = shlex.quote(tmux_session)
-    tp = shlex.quote(tmux_path)
-    buf = "optio-feedback"
-    cmd = (
-        f"{tp} -S {s} set-buffer -b {buf} -- {shlex.quote(text)} && "
-        f"{tp} -S {s} paste-buffer -d -b {buf} -t {sess} && "
-        f"sleep {_SUBMIT_SETTLE_S} && "
-        f"{tp} -S {s} send-keys -t {sess} Enter"
+    """Fake-type a message into the codex TUI and submit it.
+
+    Thin wrapper over the shared
+    :func:`optio_agents.tmux_input.send_text_to_tmux`, pinned to codex's buffer
+    name (``optio-feedback``) and settle (``_SUBMIT_SETTLE_S``) so behavior is
+    identical to the previous inline implementation."""
+    await _tmux_input.send_text_to_tmux(
+        host, tmux_path, tmux_socket, tmux_session, text,
+        buffer="optio-feedback", submit_settle=_SUBMIT_SETTLE_S,
     )
-    result = await host.run_command(cmd)
-    if result.exit_code != 0:
-        raise RuntimeError(
-            f"send_text_to_codex: tmux injection failed "
-            f"(exit {result.exit_code}): {result.stderr!r}"
-        )
+
+
+async def send_key_to_codex(
+    host: "Host", tmux_path: str, tmux_socket: str, tmux_session: str, key: str,
+) -> None:
+    """Send a single navigation keystroke into the codex TUI (iframe-input
+    empty-box TUI nav). Thin wrapper over
+    :func:`optio_agents.tmux_input.send_key_to_tmux`."""
+    await _tmux_input.send_key_to_tmux(host, tmux_path, tmux_socket, tmux_session, key)
 
 
 # --- resume bookkeeping (Stage 2; adapted from optio-grok) ------------------

optio_codex-0.2.1/src/optio_codex/info.py

@@ -0,0 +1,7 @@
+from optio_agents import AgentInfo
+
+AGENT_INFO = AgentInfo(
+    slug="codex",
+    name="Codex",
+    url="https://openai.com/codex",
+)

optio_codex-0.2.1/src/optio_codex/models.py

@@ -0,0 +1,126 @@
+"""Available-model list for the codex conversation widget's model picker.
+
+============================================================================
+MODEL-SWITCH MECHANISM — pinned from the app-server contract (codex-cli
+0.142.5 schema dump + upstream README; see the conversation docstring).
+============================================================================
+
+Decision: **INLINE** (opencode/grok-style), NOT restart (claudecode-style) —
+and codex needs NO dedicated set-model request at all: a ``model`` override
+on ``turn/start`` "become[s] the default for subsequent turns" (README,
+turn/start). So ``CodexConversation.set_control("model", …)`` just pins the
+model sent with the next ``turn/start``; the session body needs no
+model_change_requested restart loop.
+
+MODEL LIST source: the ``model/list`` request, answered in-session
+(``{data:[Model], nextCursor}``; ``Model`` carries ``id``, ``displayName``,
+``hidden``, ``isDefault``). The conversation captures the raw result at
+bootstrap; this module maps it to the widget shape. There is no CLI listing
+tier (unlike grok) — live result → static fallback, nothing in between.
+"""
+from __future__ import annotations
+
+from optio_agents.session_controls import (
+    SessionControl,
+    effort_control,
+    model_control,
+)
+
+# Shown when the live model/list is unavailable (fake agents, offline, error
+# response). Version-sensitive vendor strings; update alongside the pinned
+# codex-cli version. ``efforts`` (per-model graded reasoning levels) is empty
+# in the fallback — the effort control only appears once the live model/list
+# advertises ``supportedReasoningEfforts``.
+FALLBACK_MODELS: dict = {
+    "models": [
+        {"id": "gpt-5.5", "label": "GPT-5.5", "disabled": False,
+         "efforts": [], "defaultEffort": None},
+        {"id": "gpt-5.4-mini", "label": "GPT-5.4 Mini", "disabled": False,
+         "efforts": [], "defaultEffort": None},
+    ],
+    "default": "gpt-5.5",
+}
+
+
+def parse_model_list(result: "dict | None") -> dict:
+    """Map a raw ``model/list`` result to the widget shape
+    ``{models:[{id,label,disabled,efforts,defaultEffort}], default}``.
+
+    Hidden models are omitted; ``default`` is the ``isDefault`` entry's id
+    (None when absent). Each model also carries its graded reasoning capability
+    read from the app-server ``Model`` schema: ``efforts`` =
+    ``supportedReasoningEfforts`` (ordered; empty ⇒ no graded effort for that
+    model) and ``defaultEffort`` = ``defaultReasoningEffort``. Missing /
+    malformed input returns the static fallback (never raises, never falsely
+    empties the picker).
+    """
+    if not isinstance(result, dict):
+        return _copy_fallback()
+    data = result.get("data")
+    if not isinstance(data, list):
+        return _copy_fallback()
+    out: list[dict] = []
+    default: str | None = None
+    for m in data:
+        if not isinstance(m, dict):
+            continue
+        mid = m.get("id")
+        if not isinstance(mid, str) or not mid or m.get("hidden"):
+            continue
+        efforts = m.get("supportedReasoningEfforts")
+        out.append({
+            "id": mid,
+            "label": m.get("displayName") or mid,
+            "disabled": False,
+            "efforts": [
+                e["reasoningEffort"] for e in efforts
+                if isinstance(e, dict) and isinstance(e.get("reasoningEffort"), str)
+            ] if isinstance(efforts, list) else [],
+            "defaultEffort": m.get("defaultReasoningEffort"),
+        })
+        if m.get("isDefault"):
+            default = mid
+    if not out:
+        return _copy_fallback()
+    return {"models": out, "default": default}
+
+
+def effort_for_model(
+    model_list: dict, model_id: "str | None"
+) -> "tuple[list[str], str | None]":
+    """Return ``(levels, default)`` graded-reasoning capability for
+    ``model_id`` from a ``parse_model_list`` result. ``([], None)`` when the
+    model is unknown or advertises no ``supportedReasoningEfforts``."""
+    for m in model_list.get("models", []):
+        if m.get("id") == model_id:
+            return list(m.get("efforts") or []), m.get("defaultEffort")
+    return [], None
+
+
+def build_controls(
+    model_list: dict,
+    current_model: "str | None",
+    requested_effort: "str | None",
+) -> "list[SessionControl]":
+    """Build codex's session-control set for the current model: the
+    ``id="model"`` picker plus, WHEN the current model supports graded
+    reasoning, the ``id="reasoning_effort"`` slider. An unsupported model
+    yields no effort control (Spec-B model-dependent presence). The slider's
+    current value is the requested effort when it is valid for the model, else
+    the model's default. Re-derived on every model change so effort presence /
+    levels follow the model."""
+    controls: list[SessionControl] = [
+        model_control(models=model_list["models"], current=current_model),
+    ]
+    levels, default = effort_for_model(model_list, current_model)
+    if levels:
+        current = requested_effort if requested_effort in levels else default
+        controls.append(effort_control(levels=levels, current=current))
+    return controls
+
+
+def _copy_fallback() -> dict:
+    return {
+        "models": [dict(m) for m in FALLBACK_MODELS["models"]],
+        "default": FALLBACK_MODELS["default"],
+    }