Merge #TASK-933: custom agent model merge semantics

absent=preserve, explicit empty=reset to provider default. Gateway payload
Option<String> + store resolver, CLI omit-when-absent + --clear-model, mobile
always-present model/effort/tier. Reviewed + independently verified (gateway 10,
CLI 28, mobile 57 tests; live e2e preserves reviewer model).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Pyiner

docs/design/custom-agent-model-merge-contract.md

@@ -0,0 +1,120 @@
+# Custom Agent Model Merge Contract
+
+## Problem
+
+`PUT /api/custom-agents/{agent_id}` and `POST /api/custom-agents` currently
+treat omitted model fields as empty strings because the request payload uses
+`String` fields with `#[serde(default)]`. That collapses two different client
+intents:
+
+- field absent: keep the stored value when updating an existing agent
+- field present with `""`: replace the stored value with provider default
+
+The same endpoint already has merge semantics for adjacent optional fields such
+as provider environment, default workspace, and avatar data. Model selection,
+reasoning effort, and service tier should use the same contract.
+
+## Contract
+
+For custom-agent upsert requests:
+
+| Request state | Existing agent update | New agent create |
+| --- | --- | --- |
+| `model` absent | keep stored `model` | store `""` |
+| `model: "x"` | store `"x"` after trimming | store `"x"` after trimming |
+| `model: ""` | store `""` (provider default) | store `""` |
+
+`model_reasoning_effort` and `model_service_tier` follow the same rules. The
+camelCase aliases `modelReasoningEffort` and `modelServiceTier` remain accepted.
+
+Stored `CustomAgentProfile` fields stay as `String`; the tri-state behavior is
+only a request-layer concern.
+
+## Design
+
+### Gateway
+
+- Change `CustomAgentUpsertPayload.model`, `model_reasoning_effort`, and
+  `model_service_tier` from `String` to `Option<String>`.
+- Change `UpsertCustomAgentRequest` the same way.
+- In `CustomAgentStore::upsert_agent`, resolve each field with one helper:
+  - `Some(value)` trims and stores the value, including `""`.
+  - `None` keeps the existing profile value.
+  - `None` on create stores `""`.
+- Keep built-in-agent modification rejection before persisting changes.
+- Keep provider environment, auth, workspace, avatar, native config, and prompt
+  behavior unchanged.
+
+### CLI
+
+- Stop serializing `model`, `model_reasoning_effort`, and
+  `model_service_tier` when the caller omitted the matching option. This lets
+  the gateway preserve existing values on update.
+- Keep create behavior unchanged: omitted keys create empty stored values, which
+  means provider defaults.
+- Add `--clear-model` to `garyx agent update` and `garyx agent upsert`; it sends
+  `model: ""` explicitly and conflicts with `--model`.
+- Keep existing explicit-empty support for reasoning effort and service tier,
+  because passing `--model-reasoning-effort ""` or `--model-service-tier ""`
+  still sends an explicit replacement value.
+- Update help text so omission on update/upsert is described as preserve, while
+  omission on create remains provider default.
+
+### Mobile
+
+`GaryxCustomAgentRequest` already has optional request fields, so its shape does
+not change. The mobile create/edit flows must send model and reasoning effort
+values whenever the user is saving those controls:
+
+- create: send the trimmed `model` and `model_reasoning_effort` strings even
+  when they are empty
+- update: send the next model, next reasoning effort, and preserved service tier
+  strings even when they are empty
+
+This keeps "reset to Provider default" working under the new absent-as-preserve
+contract.
+
+Desktop already sends model values from required controls, so no desktop change
+is planned.
+
+## Tradeoffs
+
+- Using `Option<String>` at the request boundary is more explicit than adding a
+  separate clear flag to the API. JSON already has a native absent-vs-present
+  distinction, and existing optional fields use that pattern.
+- Keeping stored fields as `String` avoids a storage migration and preserves
+  the existing provider-default representation.
+- The CLI grows only the missing `--clear-model` affordance. Empty string
+  values remain supported for the other two fields to avoid a broader CLI flag
+  expansion.
+
+## Rollout/compatibility
+
+The new gateway treats absent model fields as preserve. Older iOS builds send
+`nil` for empty model controls, so those builds temporarily lose the ability to
+reset an agent model or reasoning effort to Provider default after the gateway
+change ships. They can still preserve existing settings.
+
+Ship the gateway and iOS app changes together so mobile regains explicit
+empty-string clears. Desktop sends concrete model values from required controls,
+and the CLI change adds an explicit clear path, so desktop and CLI are not
+affected by this compatibility window.
+
+## Validation
+
+- Gateway store tests:
+  - update without model fields preserves existing model settings
+  - update with `Some("")` clears model settings
+  - update with `Some("x")` replaces model settings
+  - create without model fields stores empty strings
+- Gateway build coverage: `cargo build`
+- Focused gateway tests: `cargo test -p garyx-gateway custom_agents`
+- CLI tests:
+  - update without model options omits the three keys
+  - update with `--clear-model` sends `model: ""`
+- CLI end-to-end check against a real persisted agent: dump current agent,
+  update without `--model`, and confirm the stored model is preserved.
+- Mobile core test: `GaryxCustomAgentRequest(model: "")` encodes a present
+  `"model": ""` key.
+- iOS app target build: run `xcodebuild` for the app target because SwiftPM
+  tests do not cover app-target wiring.

garyx-gateway/src/agent_identity.rs

@@ -236,9 +236,9 @@ mod tests {
                 agent_id: "reviewer".to_owned(),
                 display_name: "Reviewer".to_owned(),
                 provider_type: ProviderType::CodexAppServer,
-                model: "gpt-5".to_owned(),
-                model_reasoning_effort: "high".to_owned(),
-                model_service_tier: "priority".to_owned(),
+                model: Some("gpt-5".to_owned()),
+                model_reasoning_effort: Some("high".to_owned()),
+                model_service_tier: Some("priority".to_owned()),
                 provider_env: None,
                 auth_source: None,
                 base_url: None,

garyx-gateway/src/agent_team_provider/tests.rs

@@ -21,9 +21,9 @@ async fn test_dispatcher() -> GatewaySubAgentDispatcher {
             agent_id: "planner".to_owned(),
             display_name: "Planner".to_owned(),
             provider_type: ProviderType::ClaudeCode,
-            model: String::new(),
-            model_reasoning_effort: String::new(),
-            model_service_tier: String::new(),
+            model: Some(String::new()),
+            model_reasoning_effort: Some(String::new()),
+            model_service_tier: Some(String::new()),
             provider_env: None,
             auth_source: None,
             base_url: None,
@@ -41,9 +41,9 @@ async fn test_dispatcher() -> GatewaySubAgentDispatcher {
             agent_id: "reviewer".to_owned(),
             display_name: "Reviewer".to_owned(),
             provider_type: ProviderType::ClaudeCode,
-            model: String::new(),
-            model_reasoning_effort: String::new(),
-            model_service_tier: String::new(),
+            model: Some(String::new()),
+            model_reasoning_effort: Some(String::new()),
+            model_service_tier: Some(String::new()),
             provider_env: None,
             auth_source: None,
             base_url: None,

garyx-gateway/src/api.rs

@@ -304,11 +304,11 @@ pub struct CustomAgentUpsertPayload {
     pub display_name: String,
     pub provider_type: garyx_models::ProviderType,
     #[serde(default)]
-    pub model: String,
+    pub model: Option<String>,
     #[serde(default, alias = "modelReasoningEffort")]
-    pub model_reasoning_effort: String,
+    pub model_reasoning_effort: Option<String>,
     #[serde(default, alias = "modelServiceTier")]
-    pub model_service_tier: String,
+    pub model_service_tier: Option<String>,
     #[serde(default, alias = "env", alias = "providerEnv")]
     pub provider_env: Option<HashMap<String, String>>,
     #[serde(default, alias = "authSource")]

garyx-gateway/src/application/chat/prepare/tests.rs

@@ -166,9 +166,9 @@ async fn prepare_chat_request_resolves_provider_and_system_prompt_from_thread_ag
             agent_id: "spec-review".to_owned(),
             display_name: "Spec Review".to_owned(),
             provider_type: ProviderType::CodexAppServer,
-            model: "gpt-5-codex".to_owned(),
-            model_reasoning_effort: "xhigh".to_owned(),
-            model_service_tier: String::new(),
+            model: Some("gpt-5-codex".to_owned()),
+            model_reasoning_effort: Some("xhigh".to_owned()),
+            model_service_tier: Some(String::new()),
             provider_env: None,
             auth_source: None,
             base_url: None,

garyx-gateway/src/custom_agents.rs

@@ -16,11 +16,11 @@ pub struct UpsertCustomAgentRequest {
     pub display_name: String,
     pub provider_type: ProviderType,
     #[serde(default)]
-    pub model: String,
+    pub model: Option<String>,
     #[serde(default, alias = "modelReasoningEffort")]
-    pub model_reasoning_effort: String,
+    pub model_reasoning_effort: Option<String>,
     #[serde(default, alias = "modelServiceTier")]
-    pub model_service_tier: String,
+    pub model_service_tier: Option<String>,
     #[serde(default, alias = "env", alias = "providerEnv")]
     pub provider_env: Option<HashMap<String, String>>,
     #[serde(default, alias = "authSource")]
@@ -134,9 +134,13 @@ impl CustomAgentStore {
     ) -> Result<CustomAgentProfile, String> {
         let agent_id = request.agent_id.trim();
         let display_name = request.display_name.trim();
-        let model = request.model.trim();
-        let model_reasoning_effort = request.model_reasoning_effort.trim();
-        let model_service_tier = request.model_service_tier.trim();
+        let requested_model = request.model.map(|value| value.trim().to_owned());
+        let requested_model_reasoning_effort = request
+            .model_reasoning_effort
+            .map(|value| value.trim().to_owned());
+        let requested_model_service_tier = request
+            .model_service_tier
+            .map(|value| value.trim().to_owned());
         let provider_env = request.provider_env.map(|values| {
             values
                 .into_iter()
@@ -195,6 +199,15 @@ impl CustomAgentStore {
                 .and_then(|existing| existing.avatar_data_url.clone()),
         };
         let existing = inner.get(agent_id);
+        let model = requested_model
+            .or_else(|| existing.map(|profile| profile.model.clone()))
+            .unwrap_or_default();
+        let model_reasoning_effort = requested_model_reasoning_effort
+            .or_else(|| existing.map(|profile| profile.model_reasoning_effort.clone()))
+            .unwrap_or_default();
+        let model_service_tier = requested_model_service_tier
+            .or_else(|| existing.map(|profile| profile.model_service_tier.clone()))
+            .unwrap_or_default();
         let provider_env = provider_env
             .or_else(|| existing.map(|profile| profile.provider_env.clone()))
             .unwrap_or_default();
@@ -219,9 +232,9 @@ impl CustomAgentStore {
             agent_id: agent_id.to_owned(),
             display_name: display_name.to_owned(),
             provider_type: request.provider_type,
-            model: model.to_owned(),
-            model_reasoning_effort: model_reasoning_effort.to_owned(),
-            model_service_tier: model_service_tier.to_owned(),
+            model,
+            model_reasoning_effort,
+            model_service_tier,
             provider_env,
             auth_source,
             base_url,