feat: 对齐 codex-cli 能力面——CLI typed 方法 + app-server 协议扩展

CLI 路线（依据官方 developer-commands 文档）：
- debug typed：debugModels / debugModelsBundled / debugPromptInput
- mcp HTTP 注册 typed：mcpAddUrl / mcpAddUrlWithBearer（--url +
  --bearer-token-env-var，token 不落 config.toml）
- plugin 生命周期 typed：pluginAdd/List/Remove + pluginMarketplace
  Add/List/Remove/Upgrade
- cloud typed：cloudExec（--env + query）/ cloudList（--json）
- features typed：featuresEnable/Disable/List
- review 自定义指令：reviewPrompt

app-server WS 路线（依据官方 app-server 文档 + app-server-protocol v2 形状）：
- 新增 CodexAppServerRpc：短连接通用 JSON-RPC，含文档要求的容错
  initialize 握手（老 daemon 不支持时忽略错误继续）
- thread 生命周期：listThreads(limit[,cursor]) / readThread /
  readThreadRaw / forkThread / archiveThread / unarchiveThread /
  deleteThread
- turn 控制：interruptTurn(threadId,turnId) / steerTurn(threadId,
  expectedTurnId,prompt)——线程状态在服务端，原 turn 连接流式输出
  中亦可用
- turn/started 捕获 turnId：AppServerTurnRequest.onTurnStarted 回调 +
  AppServerTurnResult.turnId，支撑运行中转向/打断
- 逃生通道 execRpc(method,params) 覆盖未建模方法
- 假服务器同步扩展 + E2E：协议握手、thread 生命周期全链路、turnId
  暴露；修复 Rpc 主请求结果未桥接到实例 future 的确定性缺陷

测试 230 个全绿（+3）。README 双语同步。

Author: loong10k

README.md

@@ -79,6 +79,8 @@ Typical scenarios:
 | Auth / MCP / misc | Active development | `login`, `loginWithApiKey`, `loginWithAccessToken`, `loginDeviceAuth`, `loginStatus`, `logout`, `mcpList` / `mcpAdd` / `mcpGet` / `mcpRemove` / `mcpLogin` / `mcpLogout`, `update`, `features`, `completion`, `app` |
 | Session admin | Active development | `archiveSession`, `unarchiveSession`, `queue`, `deleteSession`, `deleteSessionForce`, `agents`, `migrateRollouts` |
 | App-server WebSocket route | Active development | `CodexAppServerClient.runTurn` / `runTurnAsync`, `thread/start` / `thread/resume`, agent-message deltas, `sessionKey → threadId` LRU (1000) |
+| App-server protocol surface | Active development | `thread/list` / `read` / `fork` / `archive` / `unarchive` / `delete`, `turn/interrupt` / `turn/steer`, `model/list`-style escape hatch `execRpc`; `turnId` exposed via `onTurnStarted` + `AppServerTurnResult` |
+| CLI typed additions | Active development | `debugModels(Bundled)` / `debugPromptInput`, `mcpAddUrl(WithBearer)`, `pluginAdd/List/Remove` + `pluginMarketplace*`, `cloudExec` / `cloudList`, `featuresEnable/Disable/List`, `reviewPrompt` |
 | Config model | Active development | `CodexClientConfig` POJO (plain, Spring-bindable), `CodexAppServerConfig` POJO |
 
 > **Note**: `codex mcp-server` was removed upstream — `CodexClient.mcpServer()`
@@ -296,6 +298,25 @@ try (CodexAppServerClient client = new CodexAppServerClient(config)) {
 }
 ```
 
+### 8.4 App-server protocol operations
+
+```java
+try (CodexAppServerClient client = new CodexAppServerClient(config)) {
+    List<AppServerThread> threads = client.listThreads(20);
+    AppServerThread forked = client.forkThread("th_123");
+    client.steerTurn("th_123", "turn_9", "也检查一下测试覆盖率");   // redirect a running turn
+    client.interruptTurn("th_123", "turn_9");                      // cancel a running turn
+    client.archiveThread("th_123");
+    String raw = client.execRpc("model/list", Map.of("limit", 10)); // escape hatch
+}
+```
+
+Lifecycle calls run over a short-lived connection with the documented
+tolerant `initialize` handshake; thread state is server-side, so
+`steerTurn` / `interruptTurn` work while the original turn connection is
+still streaming. Running turns expose their id via
+`AppServerTurnRequest.onTurnStarted` and `AppServerTurnResult.getTurnId()`.
+
 The turn maps to `thread/start` (or `thread/resume` when `sessionKey` already
 maps to a thread id) → `turn/start` → `item/completed` (only agent messages
 surface) → `turn/completed`. Unknown notifications are logged at debug level

README.zh-CN.md

@@ -76,6 +76,8 @@ SDK 覆盖：
 | 认证 / MCP / 其他 | 活跃开发 | `login`、`loginWithApiKey`、`loginWithAccessToken`、`loginDeviceAuth`、`loginStatus`、`logout`、`mcpList` / `mcpAdd` / `mcpGet` / `mcpRemove` / `mcpLogin` / `mcpLogout`、`update`、`features`、`completion`、`app` |
 | 会话管理 | 活跃开发 | `archiveSession`、`unarchiveSession`、`queue`、`deleteSession`、`deleteSessionForce`、`agents`、`migrateRollouts` |
 | App-server WebSocket 路线 | 活跃开发 | `CodexAppServerClient.runTurn` / `runTurnAsync`、`thread/start` / `thread/resume`、agent 消息 delta、`sessionKey → threadId` LRU（1000） |
+| App-server 协议面 | 活跃开发 | `thread/list` / `read` / `fork` / `archive` / `unarchive` / `delete`、`turn/interrupt` / `turn/steer`、逃生通道 `execRpc`；`turnId` 经 `onTurnStarted` 与 `AppServerTurnResult` 暴露 |
+| CLI typed 补齐 | 活跃开发 | `debugModels(Bundled)` / `debugPromptInput`、`mcpAddUrl(WithBearer)`、`pluginAdd/List/Remove` + `pluginMarketplace*`、`cloudExec` / `cloudList`、`featuresEnable/Disable/List`、`reviewPrompt` |
 | 配置模型 | 活跃开发 | `CodexClientConfig` POJO（纯对象，可绑定 Spring 配置）、`CodexAppServerConfig` POJO |
 
 > **注意**：上游已移除 `codex mcp-server` 子命令——`CodexClient.mcpServer()`
@@ -288,6 +290,24 @@ try (CodexAppServerClient client = new CodexAppServerClient(config)) {
 }
 ```
 
+### 8.4 App-server 协议操作
+
+```java
+try (CodexAppServerClient client = new CodexAppServerClient(config)) {
+    List<AppServerThread> threads = client.listThreads(20);
+    AppServerThread forked = client.forkThread("th_123");
+    client.steerTurn("th_123", "turn_9", "也检查一下测试覆盖率");   // 运行中转向
+    client.interruptTurn("th_123", "turn_9");                      // 运行中打断
+    client.archiveThread("th_123");
+    String raw = client.execRpc("model/list", Map.of("limit", 10)); // 逃生通道
+}
+```
+
+生命周期调用走短连接并带文档规定的容错 `initialize` 握手；线程状态在
+服务端，因此原 turn 连接仍在流式输出时 `steerTurn` / `interruptTurn`
+同样可用。运行中的 turn 经 `AppServerTurnRequest.onTurnStarted` 与
+`AppServerTurnResult.getTurnId()` 暴露其 id。
+
 一个 turn 对应：`thread/start`（`sessionKey` 已有映射时走 `thread/resume`）→
 `turn/start` → `item/completed`（仅 agent 消息对外呈现）→ `turn/completed`。
 未知通知只记录 debug 日志，不中断 turn。失败——连接、JSON-RPC 错误、

src/main/java/io/github/easy4j/codex/CodexClient.java

@@ -789,6 +789,172 @@ public CodexCliResult apply(String taskId) {
      */
     public CodexCliResult features() { return cli.features(); }
 
+    /**
+     * Runs {@code codex debug models} — the raw model catalog as JSON.
+     *
+     * @return the raw CLI invocation result; never {@code null}.
+     * @since 3.0.0
+     */
+    public CodexCliResult debugModels() { return cli.debugModels(); }
+
+    /**
+     * Runs {@code codex debug models --bundled} — only the bundled catalog.
+     *
+     * @return the raw CLI invocation result; never {@code null}.
+     * @since 3.0.0
+     */
+    public CodexCliResult debugModelsBundled() { return cli.debugModelsBundled(); }
+
+    /**
+     * Runs {@code codex debug prompt-input <prompt>} — the model-visible
+     * prompt input list as JSON.
+     *
+     * @param prompt the prompt to render.
+     * @return the raw CLI invocation result; never {@code null}.
+     * @since 3.0.0
+     */
+    public CodexCliResult debugPromptInput(String prompt) { return cli.debugPromptInput(prompt); }
+
+    /**
+     * Runs {@code codex mcp add <name> --url <url>} — registers a streamable
+     * HTTP MCP server.
+     *
+     * @param name the MCP server name.
+     * @param url  the streamable HTTP endpoint URL.
+     * @return the raw CLI invocation result; never {@code null}.
+     * @since 3.0.0
+     */
+    public CodexCliResult mcpAddUrl(String name, String url) { return cli.mcpAddUrl(name, url); }
+
+    /**
+     * Runs {@code codex mcp add <name> --url <url> --bearer-token-env-var <env>}
+     * — registers an HTTP MCP server whose bearer token lives in an env var.
+     *
+     * @param name              the MCP server name.
+     * @param url               the streamable HTTP endpoint URL.
+     * @param bearerTokenEnvVar environment variable holding the bearer token.
+     * @return the raw CLI invocation result; never {@code null}.
+     * @since 3.0.0
+     */
+    public CodexCliResult mcpAddUrlWithBearer(String name, String url, String bearerTokenEnvVar) {
+        return cli.mcpAddUrlWithBearer(name, url, bearerTokenEnvVar);
+    }
+
+    /**
+     * Runs {@code codex plugin add <plugin[@marketplace]>}.
+     *
+     * @param pluginRef plugin reference.
+     * @return the raw CLI invocation result; never {@code null}.
+     * @since 3.0.0
+     */
+    public CodexCliResult pluginAdd(String pluginRef) { return cli.pluginAdd(pluginRef); }
+
+    /**
+     * Runs {@code codex plugin list}.
+     *
+     * @return the raw CLI invocation result; never {@code null}.
+     * @since 3.0.0
+     */
+    public CodexCliResult pluginList() { return cli.pluginList(); }
+
+    /**
+     * Runs {@code codex plugin remove <plugin[@marketplace]>}.
+     *
+     * @param pluginRef plugin reference to remove.
+     * @return the raw CLI invocation result; never {@code null}.
+     * @since 3.0.0
+     */
+    public CodexCliResult pluginRemove(String pluginRef) { return cli.pluginRemove(pluginRef); }
+
+    /**
+     * Runs {@code codex plugin marketplace add <source>}.
+     *
+     * @param source the marketplace source.
+     * @return the raw CLI invocation result; never {@code null}.
+     * @since 3.0.0
+     */
+    public CodexCliResult pluginMarketplaceAdd(String source) { return cli.pluginMarketplaceAdd(source); }
+
+    /**
+     * Runs {@code codex plugin marketplace list}.
+     *
+     * @return the raw CLI invocation result; never {@code null}.
+     * @since 3.0.0
+     */
+    public CodexCliResult pluginMarketplaceList() { return cli.pluginMarketplaceList(); }
+
+    /**
+     * Runs {@code codex plugin marketplace remove <name>}.
+     *
+     * @param name the marketplace name.
+     * @return the raw CLI invocation result; never {@code null}.
+     * @since 3.0.0
+     */
+    public CodexCliResult pluginMarketplaceRemove(String name) { return cli.pluginMarketplaceRemove(name); }
+
+    /**
+     * Runs {@code codex plugin marketplace upgrade <name>}.
+     *
+     * @param name the marketplace name to upgrade.
+     * @return the raw CLI invocation result; never {@code null}.
+     * @since 3.0.0
+     */
+    public CodexCliResult pluginMarketplaceUpgrade(String name) { return cli.pluginMarketplaceUpgrade(name); }
+
+    /**
+     * Runs {@code codex cloud exec --env <envId> <query>} — submits a cloud task.
+     *
+     * @param envId the cloud environment id.
+     * @param query the task query.
+     * @return the raw CLI invocation result; never {@code null}.
+     * @since 3.0.0
+     */
+    public CodexCliResult cloudExec(String envId, String query) { return cli.cloudExec(envId, query); }
+
+    /**
+     * Runs {@code codex cloud list --env <envId> --json}.
+     *
+     * @param envId the cloud environment id.
+     * @return the raw CLI invocation result; never {@code null}.
+     * @since 3.0.0
+     */
+    public CodexCliResult cloudList(String envId) { return cli.cloudList(envId); }
+
+    /**
+     * Runs {@code codex features enable <feature>}.
+     *
+     * @param feature the feature flag name.
+     * @return the raw CLI invocation result; never {@code null}.
+     * @since 3.0.0
+     */
+    public CodexCliResult featuresEnable(String feature) { return cli.featuresEnable(feature); }
+
+    /**
+     * Runs {@code codex features disable <feature>}.
+     *
+     * @param feature the feature flag name.
+     * @return the raw CLI invocation result; never {@code null}.
+     * @since 3.0.0
+     */
+    public CodexCliResult featuresDisable(String feature) { return cli.featuresDisable(feature); }
+
+    /**
+     * Runs {@code codex features list}.
+     *
+     * @return the raw CLI invocation result; never {@code null}.
+     * @since 3.0.0
+     */
+    public CodexCliResult featuresList() { return cli.featuresList(); }
+
+    /**
+     * Runs {@code codex review <prompt>} — a custom-instruction review.
+     *
+     * @param prompt the review instruction.
+     * @return the raw CLI invocation result; never {@code null}.
+     * @since 3.0.0
+     */
+    public CodexCliResult reviewPrompt(String prompt) { return cli.reviewPrompt(prompt); }
+
     /**
      * Runs {@code codex mcp-server}.
      *

src/main/java/io/github/easy4j/codex/appserver/AppServerThread.java

@@ -0,0 +1,53 @@
+/*
+ * Copyright (c) 2018-present, easy-4-java (https://github.com/easy-4-java).
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.github.easy4j.codex.appserver;
+
+import lombok.Builder;
+import lombok.Data;
+
+/**
+ * Tolerant summary of a Codex thread as returned by the app-server
+ * {@code thread/list}, {@code thread/read} and {@code thread/fork} methods.
+ *
+ * <p>The SDK accepts both camelCase and snake_case field spellings when
+ * populating this model, staying forward-compatible with protocol revisions.</p>
+ *
+ * @author <a href="https://github.com/loong10k">Loong Wan</a>
+ * @since 3.0.0
+ * @see CodexAppServerClient#listThreads(int)
+ */
+@Data
+@Builder
+public class AppServerThread {
+
+    /** Stable opaque thread identifier used by resume/fork/interrupt operations. */
+    private String id;
+
+    /** Display name (often a prompt summary); may be {@code null}. */
+    private String name;
+
+    /** Working directory captured when the thread was created; may be {@code null}. */
+    private String cwd;
+
+    /** Creation timestamp as reported by the server; may be {@code null}. */
+    private String createdAt;
+
+    /** Last-mutation timestamp as reported by the server; may be {@code null}. */
+    private String updatedAt;
+
+    /** {@code true} when the thread has been archived. */
+    private boolean archived;
+}

src/main/java/io/github/easy4j/codex/appserver/AppServerTurnRequest.java

@@ -50,6 +50,15 @@ public class AppServerTurnRequest {
      */
     private Consumer<String> onDelta;
 
+    /**
+     * Optional callback invoked when the server reports {@code turn/started}
+     * with the active turn id. Use it together with
+     * {@link CodexAppServerClient#steerTurn(String, String, String)} or
+     * {@link CodexAppServerClient#interruptTurn(String, String)} to act on a
+     * turn while it is still running.
+     */
+    private Consumer<String> onTurnStarted;
+
     /**
      * Returns the session key in a comparable form, or {@code null} when unset.
      *

src/main/java/io/github/easy4j/codex/appserver/AppServerTurnResult.java

@@ -32,6 +32,9 @@ public class AppServerTurnResult {
     /** Codex thread id the turn ran on; also the value stored in the session mapping. */
     private String threadId;
 
+    /** Turn id reported by {@code turn/started}; usable for steer/interrupt while running. */
+    private String turnId;
+
     /**
      * Concatenated text of every agent-message item completed during the turn;
      * falls back to the {@code message} carried by {@code turn/completed} when