Merge pull request #1155 from org2AI/dev/gpt56-effort-levels

fix(models): preserve GPT-5.6 effort semantics

Author: Harry19081

docs/verification-2026-08-31/Gpt56Effort.md

@@ -0,0 +1,105 @@
+# GPT-5.6 effort handling
+
+## Source and behavior
+
+OpenAI's [model documentation](https://learn.chatgpt.com/docs/models#know-when-to-use-max-or-ultra)
+distinguishes Max reasoning from Ultra's delegation mode. The desktop app may
+hide Max until it is enabled in settings. The public API's
+[GPT-5.6 model documentation](https://developers.openai.com/api/docs/models/gpt-5.6-sol)
+supports `xhigh` and `max`; `ultra` is not a public API effort.
+
+The saved account's model variants and the local Codex catalog were inspected
+read-only. Both contained `xhigh`, `max`, and `ultra` for Sol/Terra, and `xhigh`
+and `max` for Luna. No credentials, preferences, or historical sessions were
+changed. No destructive remediation or schema migration is needed for those
+records. Live and persisted capability metadata continue to take precedence
+over fallback variants.
+
+The producing paths had three inconsistencies:
+
+- Fallback model metadata omitted Max for GPT-5.6. The fallback now emits Max
+  for Sol, Terra, and Luna, with Ultra additionally available for Sol/Terra.
+- The frontend slider placed Ultra before Max, while the table/default ranking
+  omitted Ultra. All three rankings now place Ultra after Max. Separately,
+  the requested GPT-5.6 picker policy hides the standalone Max step by default:
+  Sol/Terra show Light, Medium, High, Extra High, Ultra; Luna stops at Extra High
+  because its catalog does not advertise Ultra. This policy is shared across
+  GPT-5.6 pickers, independent of the account supplying the variants.
+- Rust parsing erased Ultra into Max, while the public OpenAI effort mapper
+  also lowered `xhigh` and `max` to `high`. Parsing now retains Ultra; public
+  API requests preserve the selected `xhigh`/`max` value. Unsupported explicit
+  selections can fail at the provider instead of silently running lower effort.
+
+Max is real capability data, not malformed data. Its UI exclusion is the
+requested product behavior, not data cleanup. The catalog and request resolver
+retain Max, and an already-applied Max selection remains visible when editing
+it. Opening, dismissing, or changing Fast cannot silently turn it into another
+effort or enable Ultra delegation. After selecting a different level, the normal
+menu no longer offers Max. Other model families' Max options remain unchanged.
+
+Correctly applying a previously downgraded effort can increase active-request
+latency and usage. Ultra can additionally use the existing worker allowance;
+it does not change that allowance or create idle work.
+
+Native Codex Ultra requests send `max` reasoning and add bounded delegation
+guidance to that request's instructions. This reuses existing subagent tools,
+permissions, worker limits, and cancellation behavior. It does not enable tools,
+spawn workers itself, change cached prompts, or override user restrictions.
+This implements ORGII's delegation guidance; it does not establish full parity
+with Codex's internal orchestration.
+
+Ultra's slider fill, label, and focus ring use the existing purple theme token.
+Other levels retain the primary accent. The popup retains its existing
+Apply/Cancel workflow in this change.
+
+## Architecture coverage
+
+Layers 1–10 were considered within the changed call chain: compilation;
+existing shared effort mapping; names; Max/Ultra semantics; default handling;
+provider-specific delegation guidance; explanatory comments; serialized wire
+bodies; streaming/non-streaming parity; and live/persisted/fallback precedence.
+Unrelated session initialization, database schema, and architecture cleanup
+were intentionally excluded.
+
+## Lifecycle checks
+
+| Area               | Verdict | Evidence                                                                  | Change or reason kept                                                 | Verification                                             |
+| ------------------ | ------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------- |
+| Background work    | keep    | Existing slider-scoped visibility listener and CSS animation              | No new timers, listeners, workers, or polling                         | Hidden/visible and repeated-open listener tests          |
+| Memory             | keep    | Fixed 18 decorative comets; per-request instruction string                | No retained mode state or growing buffers                             | Source inspection and request tests                      |
+| Scope/isolation    | keep    | Ultra instructions are constructed from the current request's parsed mode | No account writes, cached-prompt mutation, or tool-permission changes | Serialized request tests preserve input and tool absence |
+| Rendering/hot path | keep    | One derived accent state; existing native range and CSS motion            | No new subscriptions; reduced-motion rules retained                   | Slider tests and SCSS compilation                        |
+
+## Verification
+
+- `pnpm exec vitest run --config config/vitest.config.ts src/components/ModelPropertiesDropdown/EffortSlider.test.ts src/util/__tests__/modelVariants.test.ts src/util/__tests__/variantEditOptions.test.ts`: 20 tests passed.
+- `pnpm exec eslint src/components/ModelPropertiesDropdown/index.tsx src/components/ModelPropertiesDropdown/EffortSlider.tsx src/components/ModelPropertiesDropdown/EffortSlider.test.ts src/util/__tests__/variantEditOptions.test.ts src/util/variantEditOptions.ts src/util/defaultModelVariant.ts src/modules/MainApp/Integrations/KeyVault/shared/ModelTable/ModelVariantInlineCard.tsx --max-warnings 0`: passed with zero warnings.
+- `pnpm run typecheck`: passed after the final picker policy change. The first
+  attempt was terminated with SIGTERM before diagnostics and is not counted
+  as a pass.
+- `cargo test -p agent_core -p key_vault --lib gpt_5_6` from `src-tauri`: 4 passed,
+  including actual mocked HTTP requests through both chat transports and the
+  fallback catalog producing boundary.
+- `~/.cargo/shared-target/debug/deps/agent_core-ed837004ecb79b26 core::providers:: --quiet`:
+  the freshly built provider test executable passed 446 tests, including native
+  Codex and public Responses serialization. Direct execution avoids rebuilding
+  or contending for the shared Cargo target lock.
+- `~/.cargo/shared-target/debug/deps/key_vault-2ea898359e39b97e codex --quiet`:
+  36 Codex catalog/discovery/credential-handling tests passed. Together with the
+  provider suite, 482 distinct Rust tests passed.
+- SCSS compilation verified the purple token, matching focus ring, and retained
+  reduced-motion rules.
+- `node scripts/quality/check-test-placement.mjs`: passed across 440 directories.
+- `rustfmt --check --edition 2021` on the six changed Rust files: passed.
+- `git diff --check`: passed.
+
+Verification used no desktop control or live LLM requests from ORGII. Mock HTTP
+requests and serialized request bodies verify the integration boundary, but do
+not prove provider acceptance or observed automatic delegation. Full-app visual
+inspection and CPU/RSS measurement were not run; no runtime performance gain is
+claimed.
+
+Performance verdict: **pass for this scoped change**. No new idle/background
+resources or retained state were introduced; listener cleanup and visibility
+gating are regression-tested. Active Ultra delegation can consume more usage
+within existing limits; its real-world latency and resource cost remain unmeasured.

src-tauri/crates/agent-core/src/core/providers/codex_native/client.rs

@@ -106,7 +106,7 @@ impl CodexNativeClient {
             ReasoningLevel::Medium => "medium",
             ReasoningLevel::High => "high",
             ReasoningLevel::ExtraHigh => "xhigh",
-            ReasoningLevel::Max | ReasoningLevel::Ultracode => "max",
+            ReasoningLevel::Max | ReasoningLevel::Ultra | ReasoningLevel::Ultracode => "max",
             ReasoningLevel::Baseline | ReasoningLevel::None => return None,
         })
     }
@@ -146,14 +146,29 @@ impl CodexNativeClient {
         );
         let reasoning = Self::codex_reasoning_effort(parsed.level)
             .map(|effort| serde_json::json!({ "effort": effort }));
+        let mut instructions = Self::required_instructions(instructions);
+        // Ultra is Max reasoning plus a delegation policy, not an API effort
+        // named `ultra`. Apply it per request so changing effort cannot leave
+        // stale mode instructions in the session's cached system prompt.
+        if parsed.level == Some(crate::providers::thinking_mode::ReasoningLevel::Ultra) {
+            instructions.push_str(
+                "\n\n## Ultra mode\n\n\
+                 Use the available subagent tools to delegate concrete, independent subtasks \
+                 in parallel when that helps complete the user's request. Keep the main agent \
+                 responsible for integration and verification, and do not duplicate delegated work. \
+                 Keep simple or tightly coupled work local. Respect all user restrictions, tool \
+                 permissions, worker limits, and cancellation rules. If delegation is unavailable \
+                 or disallowed, work directly; never enable tools or bypass restrictions to delegate.",
+            );
+        }
         let service_tier = (parsed.fast
             && Self::codex_supports_fast_service_tier(&parsed.base_model))
         .then(|| CODEX_FAST_SERVICE_TIER.to_string());
 
         ResponsesRequest {
             model: parsed.base_model,
             input,
-            instructions: Self::required_instructions(instructions),
+            instructions,
             tools: converted_tools,
             tool_choice,
             reasoning,
@@ -331,5 +346,43 @@ mod tests {
         assert_eq!(req.model, "gpt-5.6-sol");
         assert_eq!(req.reasoning.as_ref().unwrap()["effort"], "max");
         assert_eq!(req.service_tier.as_deref(), Some("priority"));
+        assert!(req.instructions.contains("## Ultra mode"));
+        assert!(req.instructions.contains("Respect all user restrictions"));
+    }
+
+    #[test]
+    fn build_responses_request_preserves_effort_and_ultra_mode_on_the_wire() {
+        let messages = [json!({"role": "system", "content": "Keep workspace edits scoped."})];
+        for base in ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"] {
+            let efforts: &[&str] = if base == "gpt-5.6-luna" {
+                &["low", "medium", "high", "xhigh", "max"]
+            } else {
+                &["low", "medium", "high", "xhigh", "max", "ultra"]
+            };
+            for effort in efforts {
+                for (fast, stream) in [(false, false), (true, true)] {
+                    let suffix = if fast { "-fast" } else { "" };
+                    let model = format!("openai/{base}-{effort}{suffix}");
+                    let req =
+                        CodexNativeClient::build_responses_request(&messages, None, &model, stream);
+                    let body = serde_json::to_value(req).unwrap();
+                    assert_eq!(body["model"], base);
+                    assert_eq!(
+                        body["reasoning"]["effort"],
+                        if *effort == "ultra" { "max" } else { effort }
+                    );
+                    assert_eq!(body["stream"], stream);
+                    assert_eq!(body.get("service_tier").is_some(), fast);
+                    let instructions = body["instructions"].as_str().unwrap();
+                    assert!(instructions.starts_with("Keep workspace edits scoped."));
+                    assert_eq!(instructions.contains("## Ultra mode"), *effort == "ultra");
+                    assert!(body.get("max_output_tokens").is_none());
+                    assert!(body.get("temperature").is_none());
+                    assert!(body.get("tools").is_none(), "Ultra must not enable tools");
+                }
+            }
+        }
+        // The mode belongs to the current request, not a mutated/cached prompt.
+        assert_eq!(messages[0]["content"], "Keep workspace edits scoped.");
     }
 }

src-tauri/crates/agent-core/src/core/providers/openai_compat/streaming/chat.rs

@@ -269,6 +269,71 @@ mod tests {
     use wiremock::matchers::{method, path};
     use wiremock::{Mock, MockServer, ResponseTemplate};
 
+    #[tokio::test]
+    async fn gpt_5_6_upper_efforts_reach_both_chat_transports() {
+        crate::test_support::install_crypto_provider_for_tests();
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/chat/completions"))
+            .respond_with(|request: &wiremock::Request| {
+                let body: Value = request.body_json().unwrap();
+                if body["stream"] == true {
+                    ResponseTemplate::new(200)
+                        .insert_header("content-type", "text/event-stream")
+                        .set_body_string(concat!(
+                            "data: {\"choices\":[{\"delta\":{\"content\":\"ok\"},\"finish_reason\":\"stop\"}]}\n\n",
+                            "data: [DONE]\n\n"
+                        ))
+                } else {
+                    ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                        "choices": [{"message": {"content": "ok"}, "finish_reason": "stop"}]
+                    }))
+                }
+            })
+            .expect(12)
+            .mount(&server)
+            .await;
+
+        let client = OpenAICompatClient::new(
+            ProviderConfig {
+                api_key: "test-key".to_string(),
+                api_base: Some(server.uri()),
+                extra_headers: HashMap::new(),
+                is_azure: false,
+            },
+            find_by_name(provider_id::OPENAI).unwrap(),
+            "gpt-5.6-sol".to_string(),
+        );
+        let messages = [serde_json::json!({"role": "user", "content": "hello"})];
+        for base in ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"] {
+            for effort in ["xhigh", "max"] {
+                for stream in [false, true] {
+                    let model = format!("{base}-{effort}");
+                    if stream {
+                        client
+                            .chat_streaming(&messages, None, &model, 1024, 0.0, &|_| {}, None)
+                            .await
+                            .unwrap();
+                    } else {
+                        client
+                            .chat(&messages, None, &model, 1024, 0.0)
+                            .await
+                            .unwrap();
+                    }
+                    let requests = server.received_requests().await.unwrap();
+                    let body: Value = requests.last().unwrap().body_json().unwrap();
+                    assert_eq!(body["model"], base);
+                    assert_eq!(body["reasoning_effort"], effort);
+                    assert_eq!(
+                        body.get("stream").and_then(Value::as_bool).unwrap_or(false),
+                        stream
+                    );
+                    assert!(body.get("thinking").is_none());
+                }
+            }
+        }
+    }
+
     #[tokio::test]
     async fn non_streaming_standard_usage_normalizes_cached_tokens() {
         crate::test_support::install_crypto_provider_for_tests();

src-tauri/crates/agent-core/src/core/providers/openai_responses/client.rs

@@ -153,6 +153,34 @@ mod tests {
         assert!(req.reasoning.is_none());
     }
 
+    #[test]
+    fn build_responses_request_preserves_upper_efforts_on_the_wire() {
+        for (base, efforts) in [
+            ("gpt-5.4", &["xhigh"][..]),
+            ("gpt-5.5", &["xhigh"][..]),
+            ("gpt-5.6-sol", &["xhigh", "max"][..]),
+            ("gpt-5.6-terra", &["xhigh", "max"][..]),
+            ("gpt-5.6-luna", &["xhigh", "max"][..]),
+        ] {
+            for effort in efforts {
+                for stream in [false, true] {
+                    let req = OpenAIResponsesClient::build_responses_request(
+                        &[],
+                        None,
+                        &format!("{base}-{effort}"),
+                        4096,
+                        0.0,
+                        stream,
+                    );
+                    let body = serde_json::to_value(req).unwrap();
+                    assert_eq!(body["model"], base);
+                    assert_eq!(body["reasoning"]["effort"], *effort);
+                    assert_eq!(body["stream"], stream);
+                }
+            }
+        }
+    }
+
     #[test]
     fn build_responses_request_non_reasoning_omits_reasoning() {
         let req =