Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .github/workflows/integration.yml
Original file line number Diff line number Diff line change
Expand Up @@ -704,7 +704,7 @@ jobs:
CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
DEPENDENCY: ${{ inputs.dependency }}
AGENT: ${{ matrix.agent }}
CODEX_VERSION: ${{ matrix.smart_routing && '0.165.0' || inputs.codex_version || '0.156.0' }}
CODEX_VERSION: ${{ matrix.smart_routing && '0.171.0' || inputs.codex_version || '0.156.0' }}
# Smoke cases already ran on this OS in the smoke job; don't repeat them here.
TEST_MARKER: live and ${{ matrix.agent }} and not soft_fail and not smoke and not anthropic_mps and not codex_relay and ${{ matrix.smart_routing && 'codex_smart_routing' || 'not codex_smart_routing' }}
ARTIFACT_NAME: integration-full-${{ matrix.agent }}-${{ matrix.os }}${{ matrix.smart_routing && '-smart-routing' || '' }}
Expand Down Expand Up @@ -913,7 +913,7 @@ jobs:
env:
DEPENDENCY: ${{ inputs.dependency }}
AGENT: ${{ matrix.agent }}
CODEX_VERSION: ${{ matrix.smart_routing && '0.165.0' || inputs.codex_version || '0.156.0' }}
CODEX_VERSION: ${{ matrix.smart_routing && '0.171.0' || inputs.codex_version || '0.156.0' }}
ARTIFACT_NAME: integration-managed-${{ matrix.agent }}${{ matrix.smart_routing && '-smart-routing' || '' }}
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
Expand Down Expand Up @@ -1002,7 +1002,7 @@ jobs:
matrix:
include: ${{ fromJSON(needs.dedicated-cuj-plan.outputs.cujs) }}
env:
CODEX_VERSION: ${{ (matrix.test == 'test_cuj4_smart_routing.py' || matrix.test == 'test_cuj7_model_discovery.py') && '0.165.0' || inputs.codex_version || '0.156.0' }}
CODEX_VERSION: ${{ (matrix.test == 'test_cuj4_smart_routing.py' || matrix.test == 'test_cuj7_model_discovery.py') && '0.171.0' || inputs.codex_version || '0.156.0' }}
UV_INDEX_URL: https://pypi.org/simple
# Every CUJ runner installs from PyPI at once; ride out slow responses instead of failing a shard.
UV_HTTP_TIMEOUT: "120"
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/polly-review.yml
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ jobs:
OMNIGENT_SKIP_WEB_UI: "true"
# Same pins as integration.yml.
CLAUDE_VERSION: 2.1.290
CODEX_VERSION: 0.165.0
CODEX_VERSION: 0.171.0
PYPI_INDEX: https://databricks.jfrog.io/artifactory/api/pypi/db-pypi/simple
steps:
- name: Resolve the pull request
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -475,7 +475,7 @@ Fields live in `~/.codex/ucode.config.toml` and `/etc/codex/managed_config.toml`
| `otel.trace_exporter` | Ignore | Create/replace | In `~/.codex/config.toml` when the config enables tracing, for Codex desktop; another exporter and other telemetry settings left alone |
| `mcp_servers` | Ignore | Merge | Managed file; add/update the config's MCP server entries, other entries left alone. A same-name entry in `~/.codex/config.toml` of the other transport (stdio vs HTTP) is removed, since Codex would merge the two into an invalid entry |
| Smart Router and Smart Router Orchestrator hooks | Merge | Merge | Launch-only `PreToolUse`, plus `UserPromptSubmit` and compact `SessionStart` with `ENABLE_SMART_ROUTER_ORCHESTRATOR=1`; Codex combines them with its native hook sources and applies project trust; `features.hooks` is enabled for a smart-routed launch |
| Native v2 collaboration | Launch-only (-c), never written | Launch-only (-c), never written | `features.multi_agent_v2.non_code_mode_only=false` and matching `root_agent_usage_hint_text` / `subagent_usage_hint_text` override saved values for the session; only for smart routing on Codex 0.164.0 or newer. User config files, general developer instructions, and native delegation-mode controls are preserved |
| Native v2 collaboration | Launch-only (-c), never written | Launch-only (-c), never written | `features.multi_agent_v2.non_code_mode_only=false` and matching `root_agent_usage_hint_text` / `subagent_usage_hint_text` override saved values for the session; only for smart routing on Codex 0.171.0 or newer. User config files, general developer instructions, and native delegation-mode controls are preserved |
| Smart Router native metadata | Launch-only (-c), never written | Launch-only (-c), never written | `responses_api_metadata.smart_router_recipe_name` records the configured recipe. The app-server interposer updates `smart_router_state` per main turn; spawn hooks stamp child task names. Reserve the state key for the interposer; a static config value would override turn updates |

</details>
Expand Down
43 changes: 22 additions & 21 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,9 +70,9 @@ When Claude Code or Codex is older than the minimum version `ug` supports, `ug`
asks before upgrading it in place. Set `UG_AUTO_UPGRADE_AGENT=1` to upgrade
without asking, for example from a launcher that manages the agent install.

Codex smart routing now requires 0.164.0, including existing managed-enabled
Codex smart routing now requires 0.171.0, including existing managed-enabled
workspaces. See the [compatibility and upgrade note](#codex-smart-routing-compatibility)
for upgrading or launching with `--disable-smart-routing`.
for upgrade offers and automatic fallback when managed routing is unavailable.

Use `ug opencode --model system.ai.glm-5-3` (or `-m`) to select a configured
model for one launch. OpenCode's `provider/model` form is also accepted.
Expand Down Expand Up @@ -725,23 +725,24 @@ Routing-enabled responses are buffered until each model step completes.

### Codex smart-routing compatibility

Smart routing now requires Codex 0.164.0
or newer, including workspaces that already enable managed smart routing. Users on
Codex 0.156–0.163 who previously launched successfully must upgrade or explicitly
run `ug codex --disable-smart-routing`. UG offers its usual upgrade prompt for a
known older version and checks the result before launching. Declining, failing, or
remaining below 0.164.0 after the upgrade keeps the routed launch blocked. This
intentional requirement ensures native v2 provides readable delegated assignments;
UG does not silently disable routing. A routed `ug codex app-server` cannot prompt,
because its stdin carries the client's protocol, so on a known older Codex it warns
on stderr and runs without smart routing instead. Ordinary launches require Codex 0.156.0
and newer. The general integration CI baseline is 0.156.0; routing cases use
0.165.0.
Smart-routed terminal launches require Codex **0.171.0 or newer**. For earlier
versions, including 0.171.0 prereleases, UG offers its usual upgrade prompt and
checks the result before enabling routing. When routing comes from the workspace's
managed default, declining or failing the upgrade warns and launches Codex without
smart routing. An update that leaves Codex below the routing minimum takes the same
fallback. Explicit routing requests remain blocked until the upgrade succeeds or
the user passes `--disable-smart-routing`.
`UG_AUTO_UPGRADE_AGENT=1` runs that upgrade without asking. The stable floor provides
native delegation and status-line provider support. Ordinary launches retain the
0.156.0 minimum; routing CI pins 0.171.0.

A routed `ug codex app-server` cannot prompt because its stdin carries the client's
protocol. On a known older Codex it warns on stderr and runs without smart routing.

An inconclusive Codex version probe is retried once with a longer timeout. If the
version is still unknown, UG stops without offering or running an update and asks
you to check `codex --version`. `--disable-smart-routing` also bypasses this routing
version check.
version is still unknown, managed routing warns and launches without routing;
explicit routing requests stop and ask you to check `codex --version`. Neither case
offers or runs an update. `--disable-smart-routing` also bypasses this routing version check.

For a routed launch, UG's `-c` overrides take precedence over saved values for
`features.multi_agent_v2.non_code_mode_only` (set to `false`),
Expand Down Expand Up @@ -804,10 +805,10 @@ managed default model, without routing or orchestration. `--enable-smart-routing
workspace smart routing keep this version, so Codex stays unrouted: ug warns and launches it
like a plain `ug codex`, without the Smart Router skills or routing hooks.

Managed smart routing launches Codex without routing when its installed version is too old
or unavailable, or when it uses a ChatGPT subscription relay. These automatic fallbacks warn
without prompting for an upgrade. Explicit routing requests still require a supported version
and direct provider.
Managed smart routing offers an upgrade when Codex is too old. If the upgrade is declined,
fails, or leaves Codex too old, the same launch warns and continues without smart routing.
An unknown version or a ChatGPT subscription relay also falls back, without an upgrade
prompt. Explicit routing requests still require a supported version and direct provider.

`SMART_ROUTER_NAME` still selects the router independently of the preset.

Expand Down
20 changes: 14 additions & 6 deletions src/ucode/agents/codex.py
Original file line number Diff line number Diff line change
Expand Up @@ -147,8 +147,8 @@
# older releases ignore it and would leave developers free to bypass the gateway.
MINIMUM_CODEX_VERSION = (0, 156, 0)
MINIMUM_CODEX_VERSION_TEXT = "0.156.0"
MINIMUM_SMART_ROUTING_CODEX_VERSION = (0, 164, 0)
MINIMUM_SMART_ROUTING_CODEX_VERSION_TEXT = "0.164.0"
MINIMUM_SMART_ROUTING_CODEX_VERSION = (0, 171, 0)
MINIMUM_SMART_ROUTING_CODEX_VERSION_TEXT = "0.171.0"
# Codex 0.134.0 introduced per-profile config files; older releases use the legacy layout.
LEGACY_LAYOUT_CODEX_VERSION = (0, 134, 0)
LEGACY_LAYOUT_CODEX_VERSION_TEXT = "0.134.0"
Expand Down Expand Up @@ -191,6 +191,14 @@ def _parse_version(value: str) -> tuple[int, int, int] | None:
return int(major), int(minor), int(patch)


def _smart_routing_version_supported(version: str) -> bool:
parsed = _parse_version(version)
return parsed is not None and (
parsed > MINIMUM_SMART_ROUTING_CODEX_VERSION
or (parsed == MINIMUM_SMART_ROUTING_CODEX_VERSION and "-" not in version.partition("+")[0])
)


def minimum_version_error(*, smart_routing_enabled: bool = False) -> str | None:
version = agent_version(SPEC["binary"])
parsed = _parse_version(version)
Expand All @@ -206,11 +214,11 @@ def minimum_version_error(*, smart_routing_enabled: bool = False) -> str | None:
"or newer. Run `codex --version` to check the installation, "
"or launch with --disable-smart-routing."
)
if parsed >= MINIMUM_SMART_ROUTING_CODEX_VERSION:
if _smart_routing_version_supported(version):
return None
return (
f"Codex smart routing requires Codex {MINIMUM_SMART_ROUTING_CODEX_VERSION_TEXT} "
f"or newer for readable delegated assignments; found {version}. "
f"or newer for native delegation and status-line provider support; found {version}. "
"Upgrade Codex or launch with --disable-smart-routing."
)
if parsed is None or parsed >= MINIMUM_CODEX_VERSION:
Expand Down Expand Up @@ -1959,8 +1967,8 @@ def _app_server_needs_newer_codex(tool_args: list[str]) -> bool:
"""
if not is_codex_app_server_launch(tool_args):
return False
parsed = _parse_version(agent_version(SPEC["binary"]))
return parsed is not None and parsed < MINIMUM_SMART_ROUTING_CODEX_VERSION
version = agent_version(SPEC["binary"])
return _parse_version(version) is not None and not _smart_routing_version_supported(version)


def launch(
Expand Down
7 changes: 7 additions & 0 deletions src/ucode/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@
configure_single_tool,
configure_tool,
ensure_bootstrap_dependencies,
ensure_minimum_version,
ensure_provider_state,
explicit_model_arg_value,
install_databricks_ai_tools_for_agents,
Expand Down Expand Up @@ -4455,6 +4456,12 @@ def _launch_tool(
routing_unavailable = codex_agent.minimum_version_error(
smart_routing_enabled=True
)
if routing_unavailable:
ensure_minimum_version(
"codex",
lambda: codex_agent.minimum_version_error(smart_routing_enabled=True),
)
routing_unavailable = None
Comment thread
masonc08 marked this conversation as resolved.
Resolved
Comment thread
masonc08 marked this conversation as resolved.
Resolved
except RuntimeError as exc:
routing_unavailable = str(exc)
Comment thread
masonc08 marked this conversation as resolved.
Resolved
if routing_unavailable:
Expand Down
38 changes: 31 additions & 7 deletions tests/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,24 @@
# Test suites and user journeys

The Codex smart-routing floor is stable 0.171.0. `test_agent_codex.py` covers the
stable boundary, prerelease rejection at the minimum, and slow-probe recovery.
`test_codex_smart_routing_v2.py` and `test_cli.py` cover explicit/managed upgrade
offers, refusal/failure, and explicit routing disable. Managed defaults warn and
continue unrouted after refusal, updater failure, EOF with updater failure, or an
update that leaves the client too old; explicit routing remains gated. Routing CI pins 0.171.0.
These are component checks; the installed-version journeys are documented in the
[integration guide](integration/README.md).

Codex calculation routing evidence supports plaintext assignments and native encrypted
delivery. Plaintext must match the audited assignment digest. For encrypted delivery,
the original spawn's ciphertext must match the child's NEW_TASK receipt, and its task
name must match the audited fallback digest. Component checks reject mismatched names,
ciphertexts, missing delivery, and non-spawn calls. This does not establish plaintext
routing for encrypted tasks; the dedicated native v2 assignment journey checks that separately.
The encrypted-request matcher accepts the exact enabled-attribution suffix on a child
task name, rejecting disabled and arbitrary suffixes. Toggle evidence still requires a
successful state change; only an explicitly denied duplicate after that success is tolerated.

Custom Codex model-service metadata has component coverage in `test_codex_catalog.py`,
`test_databricks.py`, `test_agent_codex.py`, and `test_published_agent_config.py`.
Checks resolve external and pay-per-token destinations using selected credentials;
Expand Down Expand Up @@ -1110,7 +1129,9 @@ when forwarded after UG's `--`; option-only suffixes are not mistaken for prompt
The launch-policy matrix uses one native model spelling per tool; shared parser,
classifier and routed-launch tests retain the split, equals and short-form checks.

`integration/test_ug_codex_v2_routing.py` checks native v2 on Codex 0.164.0 or newer:
`integration/test_ug_codex_v2_routing.py` checks native v2 through code mode on Codex 0.171.0 or newer.
Its pre-existing user-owned catalog opts native tools into code mode, overriding the
bundled model's direct-only preference. This transport exposes plaintext assignments:
the exact multiline assignment reaches the real hook, router, and native
child; the child completes on the routed model while the parent stays pinned.
The saved-model, `--model VALUE` and `--model=VALUE` variants cover native TUI launch;
Expand All @@ -1122,13 +1143,16 @@ the Databricks provider are preserved. `test_agent_codex.py` covers the routing
minimum version separately from ordinary launches.
`test_codex_smart_routing_v2.py` checks the native v2 overrides take precedence over
conflicting saved values in both launch paths, with saved files unchanged,
and the shared upgrade flow. Codex 0.163 cannot reach execution when the upgrade is
and the shared upgrade flow. Explicitly routed Codex 0.170 cannot reach execution when the upgrade is
declined, fails, or leaves the version below the routing minimum. Unrecognized
versions stop before an upgrade prompt or updater, including automatic-update mode;
successful and automatic upgrades of known old versions allow routing.
The managed-launch cases in `test_cli.py` exercise Codex 0.156 and 0.163 through the
real version gate: declining blocks launch, upgrading to 0.164 allows routing, and
`--disable-smart-routing` allows an ordinary launch without invoking the updater.
The managed-launch cases in `test_cli.py` exercise Codex 0.156, 0.164, 0.170, and
0.171.0-alpha.12 through the real version gate. Declining, failed/manual or automatic
updates, EOF followed by update failure, and an update that leaves the version old
all warn and launch unrouted with routing environment controls disabled. Upgrading
to stable 0.171.0 allows routing. `--disable-smart-routing` allows an ordinary launch
without invoking the updater. Every case checks launch-scoped environment restoration.
`test_codex_routing.py` checks that long Unicode assignments reach the router and hook
unchanged while audits contain their hash and length, and bound each reason to 1,000
characters. Shared-writer coverage keeps Claude's full task and reason fields intact.
Expand Down Expand Up @@ -1519,8 +1543,8 @@ Databricks Hosted configure/TUI, custom OAuth CLI TUI, and headless argument
journeys for both agents, in two parallel jobs. After smoke finishes, the full
suite runs the remaining live cases in separate agent and OS jobs, with cases
serial inside each VM. Codex smoke and general full/managed coverage retain
0.156.0. Separate required full and managed matrix rows use 0.165.0 only for
`codex_smart_routing` cases; CUJ4 also uses 0.165.0, while other CUJs retain
0.156.0. Separate required full and managed matrix rows use 0.171.0 only for
`codex_smart_routing` cases; CUJ4 also uses 0.171.0, while other CUJs retain
0.156.0. The catalog-fallback routing-off case stays on the baseline version.
The existing workflow contract tests collect both selections and require disjoint
case sets whose union preserves coverage. Windows' existing native-toggle exclusions remain.
Expand Down
2 changes: 1 addition & 1 deletion tests/e2e_cuj/test_cuj4_smart_routing.py
Original file line number Diff line number Diff line change
Expand Up @@ -205,7 +205,7 @@ def _task_inference_request(requests, agent, prompt, *, after=0):
and isinstance(content, list)
):
# Encrypted Codex child instructions leave only task_name readable.
if entry["recipient"].rsplit("/", 1)[-1] == prompt and any(
if entry["recipient"].rsplit("/", 1)[-1] in {prompt, prompt + "__sr_on"} and any(
isinstance(part, dict)
and part.get("type") == "encrypted_content"
and isinstance(part.get("encrypted_content"), str)
Expand Down
Loading
Loading