test(appserver): port canonical 2.x contracts to 3.x

Author: loong10k

src/test/java/io/github/easy4j/codex/appserver/CodexAppServerClientE2ETest.java

@@ -63,10 +63,69 @@ void shouldRunFullTurnWithDeltasAndHandshakeAuth() throws Exception {
 
             assertEquals("th_e2e", result.getThreadId());
             assertEquals("你好世界", result.getContent());
-            assertEquals("stop", result.getFinishReason());
+            assertEquals("completed", result.getFinishReason());
             assertEquals(List.of("你好", "世界"), deltas);
             assertTrue(server.authorizationSeen(), "WebSocket handshake must carry the bearer token");
-            assertEquals("thread/start", methodOf(server.receivedFrames().get(0)));
+            // 真实协议（codex ≥0.14x）：turn 前必须先 initialize 握手
+            assertEquals("initialize", methodOf(server.receivedFrames().get(0)));
+            assertTrue(methodsOf(server).contains("thread/start"),
+                    "turn must issue thread/start after the initialize handshake");
+        }
+    }
+
+
+    @Test
+    void shouldSerializeConcurrentTurnsForSameSessionKey() throws Exception {
+        try (FakeCodexAppServer server = new FakeCodexAppServer();
+                CodexAppServerClient client = new CodexAppServerClient(configFor(server))) {
+            server.holdTurnCompletions();
+
+            java.util.concurrent.CompletableFuture<AppServerTurnResult> first =
+                    client.runTurnAsync(AppServerTurnRequest.builder()
+                            .prompt("first")
+                            .sessionKey("chat-serial")
+                            .build());
+            assertTrue(server.awaitTurnStarts(1, 2_000), "first turn must reach server");
+
+            java.util.concurrent.CompletableFuture<AppServerTurnResult> second =
+                    client.runTurnAsync(AppServerTurnRequest.builder()
+                            .prompt("second")
+                            .sessionKey("chat-serial")
+                            .build());
+
+            assertFalse(server.awaitTurnStarts(2, 750),
+                    "second same-session turn must not start while first is active");
+
+            server.releaseTurnCompletions();
+            first.get(5, TimeUnit.SECONDS);
+            second.get(5, TimeUnit.SECONDS);
+            assertEquals(2, server.turnStartCount());
+        }
+    }
+
+    @Test
+    void shouldAllowConcurrentTurnsForDifferentSessionKeys() throws Exception {
+        try (FakeCodexAppServer server = new FakeCodexAppServer();
+                CodexAppServerClient client = new CodexAppServerClient(configFor(server))) {
+            server.holdTurnCompletions();
+
+            java.util.concurrent.CompletableFuture<AppServerTurnResult> first =
+                    client.runTurnAsync(AppServerTurnRequest.builder()
+                            .prompt("first")
+                            .sessionKey("chat-a")
+                            .build());
+            java.util.concurrent.CompletableFuture<AppServerTurnResult> second =
+                    client.runTurnAsync(AppServerTurnRequest.builder()
+                            .prompt("second")
+                            .sessionKey("chat-b")
+                            .build());
+
+            assertTrue(server.awaitTurnStarts(2, 2_000),
+                    "different sessions must be able to run concurrently");
+
+            server.releaseTurnCompletions();
+            first.get(5, TimeUnit.SECONDS);
+            second.get(5, TimeUnit.SECONDS);
         }
     }
 
@@ -168,8 +227,12 @@ void shouldSendInitializeHandshake() throws Exception {
             List<String> methods = server.receivedFrames().stream()
                     .map(this::methodOf)
                     .toList();
-            assertTrue(methods.contains("initialize"), "generic RPC calls must open with the initialize handshake");
-            assertTrue(methods.contains("initialized"), "initialize must be followed by the initialized notification");
+            assertTrue(methods.size() >= 3, "initialize handshake and business request must all be present");
+            assertEquals("initialize", methods.get(0));
+            assertEquals("notifications/initialized", methods.get(1),
+                    "initialize response must be acknowledged with the official notification name");
+            assertEquals("thread/list", methods.get(2),
+                    "business RPC must follow the initialized acknowledgement");
         }
     }
 

src/test/java/io/github/easy4j/codex/appserver/CodexAppServerClientTest.java

@@ -46,6 +46,30 @@ void shouldExposeSecureDefaults() {
         assertEquals(1000, config.getMaxSessionMappings());
     }
 
+
+    @Test
+    void shouldAcceptInjectedThreadMappingStore() {
+        ThreadMappingStore store = new ThreadMappingStore() {
+            @Override
+            public String get(String sessionKey) {
+                return null;
+            }
+
+            @Override
+            public void put(String sessionKey, String threadId) {
+            }
+
+            @Override
+            public void remove(String sessionKey) {
+            }
+        };
+
+        try (CodexAppServerClient client =
+                new CodexAppServerClient(configWithUrl("ws://localhost:8081"), store)) {
+            assertNotNull(client);
+        }
+    }
+
     @Test
     void shouldRejectNullRequestAndBlankPrompt() {
         try (CodexAppServerClient client = new CodexAppServerClient(configWithUrl("ws://localhost:8081"))) {

src/test/java/io/github/easy4j/codex/appserver/CodexAppServerRealIntegrationTest.java

@@ -0,0 +1,88 @@
+/*
+ * 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 org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.condition.EnabledIfSystemProperty;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * 显式真实集成测试：默认不执行，仅当同时传入
+ * {@code -Dcodex.real.base-url=http://host:port}（token 可选
+ * {@code -Dcodex.real.token=...}）时对真实 codex app-server 执行。
+ *
+ * <p>协议层验收点（2026-09-17 对 codex 0.154.0 实测提炼）：</p>
+ * <ol>
+ *   <li>initialize → notifications/initialized 握手必须先行，否则 -32600 Not initialized；</li>
+ *   <li>thread id 嵌套在 {@code result.thread.id}，顶层 {@code threadId} 为空；</li>
+ *   <li>turn 阶段失败必须来自模型/凭证层，而不是 {@code no threadId}
+ *       这类协议层错误。</li>
+ * </ol>
+ *
+ * @since 2.0.x
+ */
+@EnabledIfSystemProperty(named = "codex.real.base-url", matches = "https?://.+")
+class CodexAppServerRealIntegrationTest {
+
+    @Test
+    void listThreadsShouldPassProtocolHandshake() {
+        CodexAppServerClient client = client();
+        try {
+            // 走通用 RPC 通道（tolerant initialize）；能返回列表即证明握手与帧解析可用
+            client.listThreads(5);
+        } finally {
+            client.close();
+        }
+    }
+
+    @Test
+    void runTurnMustGetPastThreadStartEvenWithoutModelCredentials() {
+        CodexAppServerClient client = client();
+        try {
+            try {
+                client.runTurn(AppServerTurnRequest.builder()
+                        .prompt("只回复两个字母：OK")
+                        .sessionKey("real-wire-smoke")
+                        .build());
+                // 有凭证时直接完成，也算通过
+            } catch (CodexAppServerException ex) {
+                String message = String.valueOf(ex.getMessage());
+                assertFalse(message.contains("no threadId"),
+                        "threadId 解析回退到了旧协议: " + message);
+                assertFalse(message.contains("Not initialized"),
+                        "initialize 握手缺失: " + message);
+                // 无模型凭证的真实环境在此收到 turn/failed 类错误——协议层已通过
+            }
+        } finally {
+            client.close();
+        }
+    }
+
+    private CodexAppServerClient client() {
+        CodexAppServerConfig config = new CodexAppServerConfig();
+        config.setBaseUrl(System.getProperty("codex.real.base-url").trim());
+        String token = System.getProperty("codex.real.token");
+        if (token != null && !token.isBlank()) {
+            config.setToken(token.trim());
+        }
+        assertNotNull(config.getBaseUrl());
+        assertTrue(config.getConnectTimeoutMillis() > 0);
+        return new CodexAppServerClient(config);
+    }
+}