codexapi 0.12.9__tar.gz → 0.12.10__tar.gz

{codexapi-0.12.9/src/codexapi.egg-info → codexapi-0.12.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.12.9
+Version: 0.12.10
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -80,6 +80,8 @@ Use `backend="cursor"` (or set `CODEXAPI_BACKEND=cursor`) to switch to the
 Cursor agent backend.
 Use `fast=True` in Codex API calls, or `--fast` in the CLI, to opt into Codex
 fast mode. Normal mode is the default.
+Use `model="..."` and `thinking="..."` in Codex API calls to override the
+backend model and reasoning effort for a run.
 
 ## CLI
 
@@ -336,7 +338,7 @@ codexapi foreach list.txt task.yaml --retry-all
 
 ## API
 
-### `agent(prompt, cwd=None, yolo=True, flags=None, include_thinking=False, backend=None, fast=False) -> str`
+### `agent(prompt, cwd=None, yolo=True, flags=None, include_thinking=False, backend=None, fast=False, model=None, thinking=None) -> str`
 
 Runs a single agent turn and returns only the agent's message. Any reasoning
 items are filtered out.
@@ -348,8 +350,10 @@ items are filtered out.
 - `include_thinking` (bool): when true, return all agent messages joined.
 - `backend` (str | None): `codex` or `cursor` (defaults to `CODEXAPI_BACKEND` or `codex`).
 - `fast` (bool): enable Codex fast mode (defaults to normal mode).
+- `model` (str | None): backend model override. Codex maps this to `-c model=...`; Cursor maps it to `--model ...`.
+- `thinking` (str | None): Codex reasoning effort override, mapped to `-c model_reasoning_effort=...`.
 
-### `Agent(cwd=None, yolo=True, thread_id=None, flags=None, welfare=False, include_thinking=False, backend=None, fast=False)`
+### `Agent(cwd=None, yolo=True, thread_id=None, flags=None, welfare=False, include_thinking=False, backend=None, fast=False, model=None, thinking=None)`
 
 Creates a stateful session wrapper. Calling the instance sends the prompt into
 the same conversation and returns only the agent's message.
@@ -363,6 +367,8 @@ the same conversation and returns only the agent's message.
 - `include_thinking` (bool): when true, return all agent messages joined.
 - `backend` (str | None): `codex` or `cursor` (defaults to `CODEXAPI_BACKEND` or `codex`).
 - `fast` (bool): enable Codex fast mode (defaults to normal mode).
+- `model` (str | None): backend model override.
+- `thinking` (str | None): Codex reasoning effort override.
 For Cursor, `thread_id` corresponds to the `session_id` returned by the agent.
 
 ### `lead(minutes, prompt, cwd=None, yolo=True, flags=None, leadbook=None, backend=None, fast=False) -> dict`

{codexapi-0.12.9 → codexapi-0.12.10}/README.md

@@ -65,6 +65,8 @@ Use `backend="cursor"` (or set `CODEXAPI_BACKEND=cursor`) to switch to the
 Cursor agent backend.
 Use `fast=True` in Codex API calls, or `--fast` in the CLI, to opt into Codex
 fast mode. Normal mode is the default.
+Use `model="..."` and `thinking="..."` in Codex API calls to override the
+backend model and reasoning effort for a run.
 
 ## CLI
 
@@ -321,7 +323,7 @@ codexapi foreach list.txt task.yaml --retry-all
 
 ## API
 
-### `agent(prompt, cwd=None, yolo=True, flags=None, include_thinking=False, backend=None, fast=False) -> str`
+### `agent(prompt, cwd=None, yolo=True, flags=None, include_thinking=False, backend=None, fast=False, model=None, thinking=None) -> str`
 
 Runs a single agent turn and returns only the agent's message. Any reasoning
 items are filtered out.
@@ -333,8 +335,10 @@ items are filtered out.
 - `include_thinking` (bool): when true, return all agent messages joined.
 - `backend` (str | None): `codex` or `cursor` (defaults to `CODEXAPI_BACKEND` or `codex`).
 - `fast` (bool): enable Codex fast mode (defaults to normal mode).
+- `model` (str | None): backend model override. Codex maps this to `-c model=...`; Cursor maps it to `--model ...`.
+- `thinking` (str | None): Codex reasoning effort override, mapped to `-c model_reasoning_effort=...`.
 
-### `Agent(cwd=None, yolo=True, thread_id=None, flags=None, welfare=False, include_thinking=False, backend=None, fast=False)`
+### `Agent(cwd=None, yolo=True, thread_id=None, flags=None, welfare=False, include_thinking=False, backend=None, fast=False, model=None, thinking=None)`
 
 Creates a stateful session wrapper. Calling the instance sends the prompt into
 the same conversation and returns only the agent's message.
@@ -348,6 +352,8 @@ the same conversation and returns only the agent's message.
 - `include_thinking` (bool): when true, return all agent messages joined.
 - `backend` (str | None): `codex` or `cursor` (defaults to `CODEXAPI_BACKEND` or `codex`).
 - `fast` (bool): enable Codex fast mode (defaults to normal mode).
+- `model` (str | None): backend model override.
+- `thinking` (str | None): Codex reasoning effort override.
 For Cursor, `thread_id` corresponds to the `session_id` returned by the agent.
 
 ### `lead(minutes, prompt, cwd=None, yolo=True, flags=None, leadbook=None, backend=None, fast=False) -> dict`

{codexapi-0.12.9 → codexapi-0.12.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codexapi"
-version = "0.12.9"
+version = "0.12.10"
 description = "Minimal Python API for running the Codex CLI."
 readme = "README.md"
 requires-python = ">=3.8"

{codexapi-0.12.9 → codexapi-0.12.10}/src/codexapi/__init__.py

@@ -1,6 +1,6 @@
 """Minimal Python API for running agent CLIs."""
 
-from .agent import Agent, WelfareStop, agent
+from .agent import Agent, WelfareStop, agent, build_agent_flags
 from .async_agent import AsyncAgent
 from .foreach import ForeachResult, foreach
 from .pushover import Pushover
@@ -15,6 +15,7 @@ __all__ = [
     "AsyncAgent",
     "ForeachResult",
     "Pushover",
+    "build_agent_flags",
     "quota_line",
     "rate_limits",
     "Ralph",
@@ -29,4 +30,4 @@ __all__ = [
     "task_result",
     "lead",
 ]
-__version__ = "0.12.9"
+__version__ = "0.12.10"

{codexapi-0.12.9 → codexapi-0.12.10}/src/codexapi/agent.py

@@ -11,6 +11,7 @@ from . import welfare
 _CODEX_BIN = os.environ.get("CODEX_BIN", "codex")
 _CURSOR_BIN = os.environ.get("CURSOR_BIN", "cursor")
 _SUPPORTED_BACKENDS = {"codex", "cursor"}
+_CURSOR_AGENT_BIN = os.path.expanduser("~/.local/bin/cursor-agent")
 
 
 def _resolve_backend(backend):
@@ -33,12 +34,15 @@ def _ensure_backend_available(backend, env=None):
         env_var = "CODEX_BIN"
         label = "Codex CLI"
     else:
-        command = _CURSOR_BIN
+        command = _cursor_bin(env)
         env_var = "CURSOR_BIN"
         label = "Cursor agent CLI"
     merged = _merged_env(env)
     path_value = None if merged is None else merged.get("PATH")
-    resolved = shutil.which(command, path=path_value)
+    if os.path.isabs(command):
+        resolved = command if os.path.exists(command) else None
+    else:
+        resolved = shutil.which(command, path=path_value)
     if resolved:
         return resolved
     raise RuntimeError(
@@ -55,6 +59,8 @@ def agent(
     backend=None,
     env=None,
     fast=False,
+    model=None,
+    thinking=None,
 ):
     """Run a single agent turn and return only the agent's message.
 
@@ -67,12 +73,24 @@ def agent(
         backend: Agent backend to use ("codex" or "cursor").
         env: Optional environment variables for the backend subprocess.
         fast: Enable Codex fast mode. Defaults to normal mode.
+        model: Optional backend model override.
+        thinking: Optional backend reasoning/thinking effort override.
 
     Returns:
         The agent's visible response text with reasoning traces removed.
     """
     message, _thread_id, _usage = _run_agent(
-        prompt, cwd, None, yolo, flags, include_thinking, backend, env, fast
+        prompt,
+        cwd,
+        None,
+        yolo,
+        flags,
+        include_thinking,
+        backend,
+        env,
+        fast,
+        model,
+        thinking,
     )
     return message
 
@@ -106,6 +124,8 @@ class Agent:
         backend=None,
         env=None,
         fast=False,
+        model=None,
+        thinking=None,
     ):
         """Create a new session wrapper.
 
@@ -120,6 +140,8 @@ class Agent:
             backend: Agent backend to use ("codex" or "cursor").
             env: Optional environment variables for the backend subprocess.
             fast: Enable Codex fast mode. Defaults to normal mode.
+            model: Optional backend model override.
+            thinking: Optional backend reasoning/thinking effort override.
         """
         self.cwd = cwd
         self._yolo = yolo
@@ -130,6 +152,8 @@ class Agent:
         self._backend = backend
         self._env = env
         self._fast = fast
+        self._model = model
+        self._thinking = thinking
         self.last_usage = {}
 
     def __call__(self, prompt):
@@ -146,6 +170,8 @@ class Agent:
             self._backend,
             self._env,
             self._fast,
+            self._model,
+            self._thinking,
         )
         if thread_id:
             self.thread_id = thread_id
@@ -165,15 +191,49 @@ def _run_agent(
     backend,
     env,
     fast=False,
+    model=None,
+    thinking=None,
 ):
     backend = _resolve_backend(backend)
     _ensure_backend_available(backend, env)
     if backend == "codex":
-        return _run_codex(prompt, cwd, thread_id, yolo, flags, include_thinking, env, fast)
-    return _run_cursor(prompt, cwd, thread_id, yolo, flags, include_thinking, env)
+        return _run_codex(
+            prompt,
+            cwd,
+            thread_id,
+            yolo,
+            flags,
+            include_thinking,
+            env,
+            fast,
+            model,
+            thinking,
+        )
+    return _run_cursor(
+        prompt,
+        cwd,
+        thread_id,
+        yolo,
+        flags,
+        include_thinking,
+        env,
+        model,
+        thinking,
+    )
 
 
-def _run_codex(prompt, cwd, thread_id, yolo, flags, include_thinking, env, fast=False):
+def _run_codex(
+    prompt,
+    cwd,
+    thread_id,
+    yolo,
+    flags,
+    include_thinking,
+    env,
+    fast=False,
+    model=None,
+    thinking=None,
+):
     """Invoke the Codex CLI and return the message plus thread id (if any)."""
     command = [
         _CODEX_BIN,
@@ -188,6 +248,7 @@ def _run_codex(prompt, cwd, thread_id, yolo, flags, include_thinking, env, fast=
     else:
         command.append("--full-auto")
     command.extend(_codex_fast_config(fast))
+    command.extend(_agent_config_flag_parts("codex", model, thinking))
     if flags:
         command.extend(shlex.split(flags))
     if cwd:
@@ -227,11 +288,82 @@ def _codex_fast_config(fast):
     return ["-c", "features.fast_mode=false"]
 
 
-def _run_cursor(prompt, cwd, thread_id, yolo, flags, include_thinking, env):
+def _cursor_bin(env=None):
+    merged = _merged_env(env)
+    env_source = merged or os.environ
+    override = env_source.get("CURSOR_BIN", "").strip()
+    if override:
+        return os.path.expanduser(override)
+
+    path_value = None if merged is None else merged.get("PATH")
+    direct = shutil.which("cursor-agent", path=path_value)
+    if direct:
+        return direct
+    if os.path.exists(_CURSOR_AGENT_BIN):
+        return _CURSOR_AGENT_BIN
+    return _CURSOR_BIN
+
+
+def _cursor_command_prefix(env=None):
+    command = _cursor_bin(env)
+    if os.path.basename(command) == "cursor-agent":
+        return [command]
+    return [command, "agent"]
+
+
+def build_agent_flags(*, backend=None, model=None, thinking=None, flags=None):
+    """Return raw backend flags for a model/thinking configuration.
+
+    The returned string is suitable for APIs that accept the existing ``flags``
+    parameter.
+    """
+    backend = _resolve_backend(backend)
+    parts = _agent_config_flag_parts(backend, model, thinking)
+    if flags:
+        parts.extend(shlex.split(flags))
+    return shlex.join(parts)
+
+
+def _agent_config_flag_parts(backend, model=None, thinking=None):
+    backend = _resolve_backend(backend)
+    parts = []
+    model = _clean_optional_text(model)
+    thinking = _clean_optional_text(thinking)
+
+    if backend == "codex":
+        if model:
+            parts.extend(["-c", f"model={model}"])
+        if thinking:
+            parts.extend(["-c", f"model_reasoning_effort={thinking}"])
+        return parts
+
+    if model:
+        parts.extend(["--model", model])
+    if thinking:
+        raise ValueError("thinking is only supported by the codex backend")
+    return parts
+
+
+def _clean_optional_text(value):
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def _run_cursor(
+    prompt,
+    cwd,
+    thread_id,
+    yolo,
+    flags,
+    include_thinking,
+    env,
+    model=None,
+    thinking=None,
+):
     """Invoke the Cursor agent CLI and return the message plus session id (if any)."""
-    command = [
-        _CURSOR_BIN,
-        "agent",
+    command = _cursor_command_prefix(env) + [
         "--trust",
     ]
     if cwd:
@@ -240,6 +372,7 @@ def _run_cursor(prompt, cwd, thread_id, yolo, flags, include_thinking, env):
         command.extend(["--resume", thread_id])
     if yolo:
         command.append("--yolo")
+    command.extend(_agent_config_flag_parts("cursor", model, thinking))
     if flags:
         command.extend(shlex.split(flags))
     command.extend(["--print", "--output-format", "json"])

{codexapi-0.12.9 → codexapi-0.12.10}/src/codexapi/async_agent.py

@@ -12,8 +12,9 @@ import uuid
 
 from .agent import (
     _CODEX_BIN,
-    _CURSOR_BIN,
+    _agent_config_flag_parts,
     _codex_fast_config,
+    _cursor_command_prefix,
     _ensure_backend_available,
     _event_usage,
     _merged_env,
@@ -88,6 +89,8 @@ class AsyncAgent:
         env=None,
         name=None,
         fast=False,
+        model=None,
+        thinking=None,
     ):
         """Start a backend subprocess and return an async handle immediately."""
         if not isinstance(prompt, str) or not prompt.strip():
@@ -95,7 +98,7 @@ class AsyncAgent:
 
         backend = _resolve_backend(backend)
         _ensure_backend_available(backend, env)
-        command = _build_command(backend, cwd, yolo, flags, fast)
+        command = _build_command(backend, cwd, yolo, flags, fast, model, thinking)
         process = subprocess.Popen(
             command,
             stdin=subprocess.PIPE,
@@ -376,13 +379,13 @@ class AsyncAgent:
         return self._rollout_final_output
 
 
-def _build_command(backend, cwd, yolo, flags, fast=False):
+def _build_command(backend, cwd, yolo, flags, fast=False, model=None, thinking=None):
     if backend == "codex":
-        return _build_codex_command(cwd, yolo, flags, fast)
-    return _build_cursor_command(cwd, yolo, flags)
+        return _build_codex_command(cwd, yolo, flags, fast, model, thinking)
+    return _build_cursor_command(cwd, yolo, flags, model, thinking)
 
 
-def _build_codex_command(cwd, yolo, flags, fast=False):
+def _build_codex_command(cwd, yolo, flags, fast=False, model=None, thinking=None):
     command = [
         _CODEX_BIN,
         "exec",
@@ -396,6 +399,7 @@ def _build_codex_command(cwd, yolo, flags, fast=False):
     else:
         command.append("--full-auto")
     command.extend(_codex_fast_config(fast))
+    command.extend(_agent_config_flag_parts("codex", model, thinking))
     if flags:
         command.extend(shlex.split(flags))
     if cwd:
@@ -404,16 +408,15 @@ def _build_codex_command(cwd, yolo, flags, fast=False):
     return command
 
 
-def _build_cursor_command(cwd, yolo, flags):
-    command = [
-        _CURSOR_BIN,
-        "agent",
+def _build_cursor_command(cwd, yolo, flags, model=None, thinking=None):
+    command = _cursor_command_prefix() + [
         "--trust",
     ]
     if cwd:
         command.extend(["--workspace", os.fspath(cwd)])
     if yolo:
         command.append("--yolo")
+    command.extend(_agent_config_flag_parts("cursor", model, thinking))
     if flags:
         command.extend(shlex.split(flags))
     command.extend(["--print", "--output-format", "json"])

{codexapi-0.12.9 → codexapi-0.12.10/src/codexapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.12.9
+Version: 0.12.10
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -80,6 +80,8 @@ Use `backend="cursor"` (or set `CODEXAPI_BACKEND=cursor`) to switch to the
 Cursor agent backend.
 Use `fast=True` in Codex API calls, or `--fast` in the CLI, to opt into Codex
 fast mode. Normal mode is the default.
+Use `model="..."` and `thinking="..."` in Codex API calls to override the
+backend model and reasoning effort for a run.
 
 ## CLI
 
@@ -336,7 +338,7 @@ codexapi foreach list.txt task.yaml --retry-all
 
 ## API
 
-### `agent(prompt, cwd=None, yolo=True, flags=None, include_thinking=False, backend=None, fast=False) -> str`
+### `agent(prompt, cwd=None, yolo=True, flags=None, include_thinking=False, backend=None, fast=False, model=None, thinking=None) -> str`
 
 Runs a single agent turn and returns only the agent's message. Any reasoning
 items are filtered out.
@@ -348,8 +350,10 @@ items are filtered out.
 - `include_thinking` (bool): when true, return all agent messages joined.
 - `backend` (str | None): `codex` or `cursor` (defaults to `CODEXAPI_BACKEND` or `codex`).
 - `fast` (bool): enable Codex fast mode (defaults to normal mode).
+- `model` (str | None): backend model override. Codex maps this to `-c model=...`; Cursor maps it to `--model ...`.
+- `thinking` (str | None): Codex reasoning effort override, mapped to `-c model_reasoning_effort=...`.
 
-### `Agent(cwd=None, yolo=True, thread_id=None, flags=None, welfare=False, include_thinking=False, backend=None, fast=False)`
+### `Agent(cwd=None, yolo=True, thread_id=None, flags=None, welfare=False, include_thinking=False, backend=None, fast=False, model=None, thinking=None)`
 
 Creates a stateful session wrapper. Calling the instance sends the prompt into
 the same conversation and returns only the agent's message.
@@ -363,6 +367,8 @@ the same conversation and returns only the agent's message.
 - `include_thinking` (bool): when true, return all agent messages joined.
 - `backend` (str | None): `codex` or `cursor` (defaults to `CODEXAPI_BACKEND` or `codex`).
 - `fast` (bool): enable Codex fast mode (defaults to normal mode).
+- `model` (str | None): backend model override.
+- `thinking` (str | None): Codex reasoning effort override.
 For Cursor, `thread_id` corresponds to the `session_id` returned by the agent.
 
 ### `lead(minutes, prompt, cwd=None, yolo=True, flags=None, leadbook=None, backend=None, fast=False) -> dict`

{codexapi-0.12.9 → codexapi-0.12.10}/tests/test_agent_backend.py

@@ -2,11 +2,12 @@ import json
 import sys
 import unittest
 from pathlib import Path
+from unittest.mock import patch
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
 
-from codexapi.agent import _codex_fast_config, _parse_jsonl
-from codexapi.async_agent import _build_codex_command
+from codexapi.agent import _codex_fast_config, _parse_jsonl, build_agent_flags
+from codexapi.async_agent import _build_codex_command, _build_cursor_command
 
 
 class AgentBackendTests(unittest.TestCase):
@@ -34,6 +35,35 @@ class AgentBackendTests(unittest.TestCase):
         self.assertIn("service_tier=fast", command)
         self.assertIn("features.fast_mode=true", command)
 
+    def test_build_agent_flags_maps_codex_model_and_thinking_to_config(self):
+        self.assertEqual(
+            build_agent_flags(backend="codex", model="gpt-5.5", thinking="xhigh"),
+            "-c model=gpt-5.5 -c model_reasoning_effort=xhigh",
+        )
+
+    def test_build_agent_flags_maps_cursor_model_to_model_flag(self):
+        self.assertEqual(
+            build_agent_flags(backend="cursor", model="claude-4"),
+            "--model claude-4",
+        )
+
+    def test_build_agent_flags_rejects_cursor_thinking(self):
+        with self.assertRaises(ValueError):
+            build_agent_flags(backend="cursor", thinking="high")
+
+    def test_async_codex_command_can_set_model_and_thinking(self):
+        command = _build_codex_command(None, True, None, model="gpt-5.5", thinking="high")
+        self.assertIn("model=gpt-5.5", command)
+        self.assertIn("model_reasoning_effort=high", command)
+
+    def test_async_cursor_command_can_use_direct_cursor_agent(self):
+        with patch("codexapi.async_agent._cursor_command_prefix", return_value=["/tmp/cursor-agent"]):
+            command = _build_cursor_command("/tmp/work", True, None, model="composer-2")
+        self.assertEqual(command[0], "/tmp/cursor-agent")
+        self.assertNotEqual(command[1], "agent")
+        self.assertIn("--model", command)
+        self.assertIn("composer-2", command)
+
     def test_parse_jsonl_extracts_last_token_usage(self):
         output = "\n".join(
             [