Promote ChatGPT login hint to next action

Author: gaoguobin

.codex/INSTALL.md

@@ -103,11 +103,11 @@ environment API, does not print the key, does not change proxy settings, and doe
 split. Tell the user to restart Codex App or open a new CLI process after any user environment
 variable change.
 
-After a successful `install --start`, report the non-secret `chatgpt_login_hint` field. When it says
-`optional_setup_available`, tell the user they can keep the current API-key mode for third-party API
-plus global Fast, and that they should ask Codex to run `prepare-chatgpt-login` before switching
-Codex App to ChatGPT login for plugin marketplace, GitHub/Apps/connectors, manual Fast controls,
-status hints, and voice input.
+After a successful `install --start`, report the non-secret top-level `next_user_action` and
+`chatgpt_login_hint` fields. When `chatgpt_login_hint.status=optional_setup_available`, tell the
+user they can keep the current API-key mode for third-party API plus global Fast, and that they
+should ask Codex to run `prepare-chatgpt-login` before switching Codex App to ChatGPT login for
+plugin marketplace, GitHub/Apps/connectors, manual Fast controls, status hints, and voice input.
 
 Before first enable or model-path setting changes, `install --start` verifies the candidate upstream
 and auth source by sending one Codex-style `POST /v1/responses` request with `stream=true`. This is

README.md

@@ -136,8 +136,8 @@ supports it, and the exact startup hook command. Use it to spot stale editable i
 executables, or hooks pointing at the wrong checkout.
 `status.provider_auth_preparation` and the `install --start` result explain whether provider auth is
 prepared for optional ChatGPT login, without printing keys. `install --start` also returns
-`chatgpt_login_hint`, a user-facing next-step hint that tells API-key users they can keep the
-current mode, or run `prepare-chatgpt-login` before switching to ChatGPT login for plugin
+top-level `next_user_action` and `chatgpt_login_hint` fields that tell API-key users they can keep
+the current mode, or run `prepare-chatgpt-login` before switching to ChatGPT login for plugin
 marketplace, GitHub/Apps/connectors, manual Fast controls, status hints, and voice input.
 
 You can also open `http://127.0.0.1:8787/v1` in a browser. Browser-style HTML requests show a
@@ -586,8 +586,9 @@ python -m codex_fast_proxy status
 hook 命令，用来定位旧 Python、旧运行时或 hook 指向错误 checkout 的问题。
 `status.provider_auth_preparation` 和 `install --start` 结果会说明 provider auth 是否已经为可选
 ChatGPT 登录准备好，不会打印 key。`install --start` 还会返回 `chatgpt_login_hint`，明确告诉
-API-key 用户可以保持当前模式，或者在切换 ChatGPT 登录前先运行 `prepare-chatgpt-login`，以使用插件市场、
-GitHub/Apps/connectors、Fast 手动控制、状态提示和语音输入等 App UI 能力。
+API-key 用户可以保持当前模式；顶层 `next_user_action` 会提示如果要切换 ChatGPT 登录，应先运行
+`prepare-chatgpt-login`，以使用插件市场、GitHub/Apps/connectors、Fast 手动控制、状态提示和语音输入等
+App UI 能力。
 
 也可以在浏览器打开 `http://127.0.0.1:8787/v1` 查看本地只读 dashboard。它会显示 proxy 状态、
 当前 upstream、Fast 策略、顶层诊断、最近脱敏请求、是否注入 priority、SSE 状态，以及最近一次 benchmark 摘要；不会展示

skills/codex-fast-proxy/SKILL.md

@@ -134,11 +134,12 @@ python -m codex_fast_proxy uninstall
   not restart an already healthy proxy just because runtime code is stale.
 - If the user asks only to check for updates, run `check-update` and stop. It is read-only and must
   not pull, install, restart the proxy, edit Codex config, or write proxy state.
-- After a successful enable, report the JSON result and the `chatgpt_login_hint` message. If
-  `chatgpt_login_hint.status=optional_setup_available`, tell the user they can keep API-key mode for
-  third-party API plus global Fast, and should run `prepare-chatgpt-login` before switching Codex App
-  to ChatGPT login for plugin marketplace, GitHub/Apps/connectors, manual Fast controls, status
-  hints, and voice input. Avoid chaining unrelated work in the same turn.
+- After a successful enable, report the JSON result, the top-level `next_user_action`, and the
+  `chatgpt_login_hint` message. If `chatgpt_login_hint.status=optional_setup_available`, tell the
+  user they can keep API-key mode for third-party API plus global Fast, and should run
+  `prepare-chatgpt-login` before switching Codex App to ChatGPT login for plugin marketplace,
+  GitHub/Apps/connectors, manual Fast controls, status hints, and voice input. Avoid chaining
+  unrelated work in the same turn.
 
 ## Sandbox and approval discipline
 
@@ -171,7 +172,7 @@ For upstream URL changes after enable, prefer `set-upstream --upstream-base <url
 
 - Treat the JSON output as the source of truth.
 - Report `provider`, `base_url`, `upstream_base`, `service_tier_policy`, `upstream_auth`, `running`,
-  `diagnosis`, `provider_auth_preparation`, `chatgpt_login_hint`, `runtime_matches`,
+  `diagnosis`, `provider_auth_preparation`, `chatgpt_login_hint`, `next_user_action`, `runtime_matches`,
   `needs_restart`, and backup or restore status.
 - Use `status.runtime` when diagnosing stale runtime, wrong Python executable, or a startup hook that
   points at a different checkout. Do not infer hook readiness from `~/.codex/hooks.json` alone.

src/codex_fast_proxy/manager.py

@@ -723,6 +723,7 @@ def chatgpt_login_hint(login: LoginDiagnosis, auth: dict[str, Any]) -> dict[str,
                 "with ChatGPT to use richer Codex App UI features such as plugin marketplace, GitHub/Apps/"
                 "connectors, manual Fast controls, status hints, and voice input."
             ),
+            "next_user_action": "Optional: keep current mode, or sign in with ChatGPT if you want the full Codex App UI.",
         }
     if auth["upstream_auth"] == "override_configured" and auth["upstream_api_key_available"]:
         return {
@@ -731,6 +732,7 @@ def chatgpt_login_hint(login: LoginDiagnosis, auth: dict[str, Any]) -> dict[str,
                 "Optional: provider auth works now, but move it to a process or Windows user environment "
                 "variable before relying on ChatGPT login."
             ),
+            "next_user_action": "Move the provider key to a persistent environment variable before switching to ChatGPT login.",
         }
     if login.chatgpt_auth:
         return {
@@ -739,6 +741,7 @@ def chatgpt_login_hint(login: LoginDiagnosis, auth: dict[str, Any]) -> dict[str,
                 "ChatGPT login is detected, but provider auth is not split. Prepare upstream provider auth "
                 "before relying on this setup for third-party model requests."
             ),
+            "next_user_action": "Run prepare-chatgpt-login and set-upstream --upstream-api-key-env before relying on ChatGPT login.",
         }
     return {
         "status": "optional_setup_available",
@@ -747,6 +750,10 @@ def chatgpt_login_hint(login: LoginDiagnosis, auth: dict[str, Any]) -> dict[str,
             "full Codex App UI, such as plugin marketplace, GitHub/Apps/connectors, manual Fast controls, "
             "status hints, and voice input, run prepare-chatgpt-login before switching Codex App to ChatGPT login."
         ),
+        "next_user_action": (
+            "Keep API-key mode, or run prepare-chatgpt-login before switching Codex App to ChatGPT login "
+            "for plugin marketplace, GitHub/Apps/connectors, manual Fast controls, status hints, and voice input."
+        ),
     }
 
 
@@ -1815,6 +1822,7 @@ def command_install(args: argparse.Namespace) -> int:
 
     login = detect_login_mode(paths.codex_home)
     auth = upstream_auth_status(paths, settings)
+    login_hint = chatgpt_login_hint(login, auth)
     print(json_line({
         "status": "installed",
         "provider": provider,
@@ -1831,7 +1839,8 @@ def command_install(args: argparse.Namespace) -> int:
         "upstream_api_key_persistent": auth["upstream_api_key_persistent"],
         "chatgpt_login_compatible": bool(auth["upstream_api_key_persistent"]) if login.chatgpt_auth else None,
         "provider_auth_preparation": provider_auth_preparation(login, auth),
-        "chatgpt_login_hint": chatgpt_login_hint(login, auth),
+        "chatgpt_login_hint": login_hint,
+        "next_user_action": login_hint["next_user_action"],
         "backup_path": str(backup_path),
         "started": True,
         "config_switched": True,
@@ -2222,6 +2231,7 @@ def command_status(args: argparse.Namespace) -> int:
     config_matches = bool(settings and config_base_url == settings.base_url)
     needs_restart = bool(pending_restart or (healthy and not runtime_matches))
     behavior = fast_behavior(settings, login)
+    login_hint = chatgpt_login_hint(login, auth) if settings else None
     diagnosis = status_diagnosis(
         settings,
         running=running,
@@ -2262,7 +2272,8 @@ def command_status(args: argparse.Namespace) -> int:
         "upstream_api_key_persistent": auth["upstream_api_key_persistent"],
         "chatgpt_login_compatible": bool(auth["upstream_api_key_persistent"]) if login.chatgpt_auth else None,
         "provider_auth_preparation": provider_auth_preparation(login, auth) if settings else None,
-        "chatgpt_login_hint": chatgpt_login_hint(login, auth) if settings else None,
+        "chatgpt_login_hint": login_hint,
+        "next_user_action": login_hint["next_user_action"] if login_hint else None,
         "config_base_url": config_base_url,
         "config_matches": config_matches,
         "startup_hook": hook_status["ready"],

tests/test_manager.py

@@ -613,6 +613,7 @@ def test_chatgpt_login_hint_reports_optional_setup_after_enable(self) -> None:
 
         self.assertEqual(hint["status"], "optional_setup_available")
         self.assertIn("prepare-chatgpt-login", hint["message"])
+        self.assertIn("prepare-chatgpt-login", hint["next_user_action"])
         self.assertIn("plugin marketplace", hint["message"])
         self.assertIn("voice input", hint["message"])
 
@@ -643,6 +644,7 @@ def test_install_start_outputs_chatgpt_login_hint(self) -> None:
 
         self.assertEqual(result["chatgpt_login_hint"]["status"], "optional_setup_available")
         self.assertIn("prepare-chatgpt-login", result["chatgpt_login_hint"]["message"])
+        self.assertIn("prepare-chatgpt-login", result["next_user_action"])
         self.assertNotIn("provider-secret", output_text)
 
     def test_validate_upstream_rejects_userinfo_query_and_fragment(self) -> None: