fix(exec+appserver): 同步 3.0.x 生产就绪加固——exit/参数原样传递/WS 缓冲上限/ws 明文告警（Jackson 2 适配）

Author: loong10k

README.md

@@ -228,6 +228,13 @@ There is no configuration file of its own. Key fields:
 
 ### 7.1 `CodexAppServerConfig` (app-server WebSocket route)
 
+> **Upgrade notes (3.0.x.x.20260630+)**: CLI-route arguments are now passed
+> to the child process raw — multi-word prompts no longer arrive at `codex`
+> wrapped in embedded literal quotes. Non-zero CLI exits now preserve the real
+> exit code and both captured streams instead of collapsing to `exitCode=-1`
+> with empty output. A bearer token over a plaintext `ws://` connection logs a
+> warning; prefer `wss://`.
+
 Plain POJO (Spring `@ConfigurationProperties`-bindable). Field names mirror the
 commonly used `CodexEndpoint` binding:
 
@@ -238,6 +245,8 @@ commonly used `CodexEndpoint` binding:
 | `connectTimeoutMillis` | int | `5000` | TCP/TLS + WebSocket handshake timeout |
 | `readTimeoutMillis` | int | `120000` | Upper bound for a whole turn (connect → `turn/completed`) |
 | `maxSessionMappings` | int | `1000` | Bound of the `sessionKey → threadId` LRU; evicted sessions start fresh threads |
+| `maxFrameChars` | int | `1048576` | Frame accumulation hard cap; oversized server frames fail the turn (`<= 0` = unbounded) |
+| `maxContentChars` | int | `1048576` | Per-turn agent-message content cap; excess is truncated with a warning (`<= 0` = unbounded) |
 
 ## 8. Core Usage / API
 

README.zh-CN.md

@@ -222,6 +222,11 @@ public class CodexDemo {
 
 ### 7.1 `CodexAppServerConfig`（app-server WebSocket 路线）
 
+> **升级注意（3.0.x.x.20260630+）**：CLI 路线的参数改为原样传给子进程——
+> 含空格的多词 prompt 不再被塞进字面双引号后发给 `codex`。CLI 非零退出现在
+> 保留真实退出码与两路输出，不再折叠为 `exitCode=-1` 加空输出。通过明文
+> `ws://` 携带 Bearer token 会打告警日志，生产环境请优先 `wss://`。
+
 纯 POJO（可绑定 Spring `@ConfigurationProperties`）。字段名与常用的
 `CodexEndpoint` 绑定保持一致：
 
@@ -232,6 +237,8 @@ public class CodexDemo {
 | `connectTimeoutMillis` | int | `5000` | TCP/TLS + WebSocket 握手超时 |
 | `readTimeoutMillis` | int | `120000` | 单个 turn 全程上限（建连 → `turn/completed`） |
 | `maxSessionMappings` | int | `1000` | `sessionKey → threadId` LRU 上限；被淘汰的会话退化为新建线程 |
+| `maxFrameChars` | int | `1048576` | 帧累积硬上限；超限的服务器帧使 turn 失败（`<= 0` = 不限） |
+| `maxContentChars` | int | `1048576` | 单 turn agent 消息内容上限；超出部分截断并告警（`<= 0` = 不限） |
 
 ## 8. 核心用法 / API
 

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

@@ -56,4 +56,19 @@ public class CodexAppServerConfig {
      * degrade to starting a fresh thread. Defaults to {@code 1000}.
      */
     private int maxSessionMappings = 1000;
+
+    /**
+     * Hard cap in characters for the frame accumulation buffer. A server frame
+     * exceeding it fails the turn with {@link CodexAppServerException}. Values
+     * {@code <= 0} mean unbounded. Defaults to 1&nbsp;MiB characters.
+     */
+    private int maxFrameChars = 1_048_576;
+
+    /**
+     * Hard cap in characters for the agent-message content accumulated per
+     * turn; excess item text is truncated (with a warning) rather than failing
+     * the turn. Values {@code <= 0} mean unbounded. Defaults to 1&nbsp;MiB
+     * characters.
+     */
+    private int maxContentChars = 1_048_576;
 }

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

@@ -101,12 +101,16 @@ class CodexAppServerTurn implements WebSocket.Listener {
      */
     CompletableFuture<AppServerTurnResult> start() {
         Objects.requireNonNull(httpClient, "httpClient");
+        String url = toWebSocketUrl(config.getBaseUrl());
+        if (hasText(config.getToken()) && url.startsWith("ws://")) {
+            log.warn("Codex app-server token is sent over an unencrypted ws:// connection; prefer wss:// in production");
+        }
         WebSocket.Builder builder = httpClient.newWebSocketBuilder();
         builder.connectTimeout(Duration.ofMillis(config.getConnectTimeoutMillis()));
         if (hasText(config.getToken())) {
             builder.header("Authorization", "Bearer " + config.getToken().trim());
         }
-        builder.buildAsync(URI.create(toWebSocketUrl(config.getBaseUrl())), this)
+        builder.buildAsync(URI.create(url), this)
                 .whenComplete((socket, error) -> {
                     if (Objects.nonNull(error)) {
                         completeError(new CodexAppServerException("Codex WebSocket connection failed", error));
@@ -158,6 +162,11 @@ void begin() {
 
     @Override
     public CompletionStage<?> onText(WebSocket socket, CharSequence data, boolean last) {
+        if (frameBuffer.length() + data.length() > effectiveMaxFrameChars()) {
+            completeError(new CodexAppServerException(
+                    "Codex frame buffer exceeded maxFrameChars=" + config.getMaxFrameChars()));
+            return null;
+        }
         frameBuffer.append(data);
         if (last) {
             String frame = frameBuffer.toString();
@@ -233,10 +242,32 @@ private void onItemCompleted(JsonNode params) {
         if (!hasText(text)) {
             return;
         }
-        content.append(text);
-        if (Objects.nonNull(request.getOnDelta())) {
-            request.getOnDelta().accept(text);
+        String applied = truncateToContentCap(text);
+        content.append(applied);
+        if (!applied.isEmpty() && Objects.nonNull(request.getOnDelta())) {
+            request.getOnDelta().accept(applied);
+        }
+    }
+
+    /** Applies the {@code maxContentChars} hard cap; excess text is dropped with a single warning. */
+    private String truncateToContentCap(String text) {
+        int cap = effectiveMaxContentChars();
+        if (content.length() >= cap) {
+            return "";
+        }
+        if (content.length() + text.length() > cap) {
+            log.warn("Codex turn content truncated at maxContentChars={}", config.getMaxContentChars());
+            return text.substring(0, cap - content.length());
         }
+        return text;
+    }
+
+    private int effectiveMaxFrameChars() {
+        return config.getMaxFrameChars() <= 0 ? Integer.MAX_VALUE : config.getMaxFrameChars();
+    }
+
+    private int effectiveMaxContentChars() {
+        return config.getMaxContentChars() <= 0 ? Integer.MAX_VALUE : config.getMaxContentChars();
     }
 
     private void onTurnCompleted(JsonNode params) {

src/main/java/io/github/easy4j/codex/cli/CodexCliExecutor.java

@@ -18,6 +18,7 @@
 import io.github.easy4j.codex.CodexClientConfig;
 import org.apache.commons.exec.CommandLine;
 import org.apache.commons.exec.DefaultExecutor;
+import org.apache.commons.exec.ExecuteException;
 import org.apache.commons.exec.ExecuteWatchdog;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -79,6 +80,10 @@ public CodexCliExecutor(CodexClientConfig config) {
      *   <li>Process timeout &mdash; {@link CodexCliResult#isTimeout()} returns
      *       {@code true}; exit code is {@code -1}; stderr contains the timeout
      *       notice.</li>
+     *   <li>Non-zero process exit &mdash; the real exit code is preserved in
+     *       {@link CodexCliResult#getExitCode()}, and both captured streams are
+     *       returned as-is ({@link CodexCliResult#isSuccess()} is simply
+     *       {@code exitCode == 0}).</li>
      *   <li>IOException (missing executable, permission denied, etc.) &mdash;
      *       the {@link IOException#getMessage()} is captured in
      *       {@link CodexCliResult#getStderr()} and the exit code is {@code -1}.</li>
@@ -113,7 +118,11 @@ private CodexCliResult runProcess(String stdin, String... args) {
         CommandLine cmd = CommandLine.parse(config.getLocalExecutable());
         for (String arg : args) {
             if (arg != null) {
-                cmd.addArgument(arg);
+                // handleQuoting=false: the child is spawned via exec(argv), not
+                // a shell — commons-exec's default quoting would embed literal
+                // double quotes inside arguments containing spaces (prompts,
+                // config overrides, paths), corrupting them on arrival.
+                cmd.addArgument(arg, false);
             }
         }
 
@@ -131,6 +140,7 @@ private CodexCliResult runProcess(String stdin, String... args) {
         ExecuteWatchdog watchdog = new ExecuteWatchdog(timeoutMs);
         executor.setWatchdog(watchdog);
 
+        long startNanos = System.nanoTime();
         try {
             int exitCode = executor.execute(cmd);
             String out = stdout.toString().trim();
@@ -140,6 +150,23 @@ private CodexCliResult runProcess(String stdin, String... args) {
                 return new CodexCliResult(-1, out, "codex CLI timed out after " + timeoutMs + " ms\n" + err);
             }
             return new CodexCliResult(exitCode, out, err);
+        } catch (ExecuteException e) {
+            // commons-exec throws ExecuteException for EVERY non-zero exit
+            // (and for watchdog kills). The stream pumps are joined before it
+            // is thrown, so both buffers are complete — surface them together
+            // with the real exit code instead of discarding the output. The
+            // deadline check makes the timeout verdict race-free even when
+            // {@code watchdog.killedProcess()} has not observed the kill yet.
+            String out = stdout.toString().trim();
+            String err = stderr.toString().trim();
+            boolean timedOut = watchdog.killedProcess()
+                    || System.nanoTime() - startNanos >= timeoutMs * 1_000_000L;
+            if (timedOut) {
+                return new CodexCliResult(-1, out, "codex CLI timed out after " + timeoutMs + " ms\n" + err);
+            }
+            log.debug("codex CLI failed: exitCode={}, stdout.len={}, stderr.len={}",
+                    e.getExitValue(), out.length(), err.length());
+            return new CodexCliResult(e.getExitValue(), out, err);
         } catch (IOException e) {
             return new CodexCliResult(-1, "", e.getMessage());
         }

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

@@ -261,4 +261,58 @@ void shouldCompleteWithoutErrorAfterTurnCompletedWhenSocketClosesLate() throws E
         assertTrue(turn.future().isDone());
         assertEquals("stop", turn.future().get(1, TimeUnit.SECONDS).getFinishReason());
     }
+
+    @Test
+    void shouldFailTurnWhenFrameExceedsCap() {
+        CodexAppServerConfig config = new CodexAppServerConfig();
+        config.setMaxFrameChars(8);
+        CodexAppServerTurn turn = new CodexAppServerTurn(
+                AppServerTurnRequest.builder().prompt("hi").build(), config, mapper, new ThreadMappingCache(10), null);
+
+        turn.onText(null, "way-too-long-frame-data", false);
+
+        assertTrue(turn.future().isCompletedExceptionally());
+        CompletionException ex = assertThrows(CompletionException.class, () -> turn.future().join());
+        CodexAppServerException cause = assertInstanceOf(CodexAppServerException.class, ex.getCause());
+        assertTrue(cause.getMessage().contains("maxFrameChars"));
+    }
+
+    @Test
+    void shouldTruncateContentAtCapWithoutFailingTurn() {
+        CodexAppServerConfig config = new CodexAppServerConfig();
+        config.setMaxContentChars(10);
+        List<String> deltas = new ArrayList<>();
+        CodexAppServerTurn turn = new CodexAppServerTurn(
+                AppServerTurnRequest.builder().prompt("hi").onDelta(deltas::add).build(),
+                config, mapper, new ThreadMappingCache(10), null);
+
+        turn.begin();
+        turn.handleFrame("{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{\"threadId\":\"th_1\"}}");
+        turn.handleFrame("{\"method\":\"item/completed\",\"params\":{\"item\":{\"type\":\"agentMessage\",\"text\":\"12345\"}}}");
+        turn.handleFrame("{\"method\":\"item/completed\",\"params\":{\"item\":{\"type\":\"agentMessage\",\"text\":\"67890\"}}}");
+        turn.handleFrame("{\"method\":\"item/completed\",\"params\":{\"item\":{\"type\":\"agentMessage\",\"text\":\"ABCDE\"}}}");
+        turn.handleFrame("{\"method\":\"turn/completed\",\"params\":{}}");
+
+        AppServerTurnResult result = turn.future().join();
+        assertEquals("1234567890", result.getContent());
+        assertEquals(List.of("12345", "67890"), deltas, "truncated-to-empty text must not emit a delta");
+        assertEquals("stop", result.getFinishReason());
+    }
+
+    @Test
+    void shouldTreatNonPositiveCapsAsUnbounded() {
+        CodexAppServerConfig config = new CodexAppServerConfig();
+        config.setMaxFrameChars(0);
+        config.setMaxContentChars(-1);
+        CodexAppServerTurn turn = new CodexAppServerTurn(
+                AppServerTurnRequest.builder().prompt("hi").build(), config, mapper, new ThreadMappingCache(10), null);
+
+        turn.begin();
+        turn.handleFrame("{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{\"threadId\":\"th_1\"}}");
+        turn.onText(null, "x".repeat(4096), false);
+        turn.handleFrame("{\"method\":\"turn/completed\",\"params\":{}}");
+
+        assertTrue(turn.future().isDone());
+        assertFalse(turn.future().isCompletedExceptionally());
+    }
 }

src/test/java/io/github/easy4j/codex/cli/CodexCliExecutorTest.java

@@ -64,10 +64,21 @@ void shouldCaptureExitCodeFromFailingProcess() {
 
         CodexCliResult result = executor.execute("-c", "exit 7");
 
-        assertEquals(-1, result.getExitCode());
         assertFalse(result.isSuccess());
     }
 
+    @Test
+    void shouldPreserveRealExitCodeAndStreamsOnNonZeroExit() {
+        CodexCliExecutor executor = new CodexCliExecutor(configFor("/bin/sh"));
+
+        CodexCliResult result = executor.execute("-c", "echo out-marker; echo err-marker 1>&2; exit 7");
+
+        assertEquals(7, result.getExitCode());
+        assertFalse(result.isSuccess());
+        assertTrue(result.getStdout().contains("out-marker"), "stdout must survive a non-zero exit");
+        assertTrue(result.getStderr().contains("err-marker"), "stderr must survive a non-zero exit");
+    }
+
     @Test
     void shouldReturnIoExceptionMessageWhenExecutableMissing() {
         CodexCliExecutor executor = new CodexCliExecutor(configFor("/nonexistent/path/to/codex"));
@@ -80,6 +91,16 @@ void shouldReturnIoExceptionMessageWhenExecutableMissing() {
         assertFalse(result.getStderr().isEmpty());
     }
 
+    @Test
+    void shouldPassArgumentsRawWithoutEmbeddedQuotes() {
+        CodexCliExecutor executor = new CodexCliExecutor(configFor("/bin/echo"));
+
+        CodexCliResult result = executor.execute("Write a failing test", "-c", "key=some value");
+
+        assertEquals("Write a failing test -c key=some value", result.getStdout(),
+                "multi-word arguments must arrive without embedded literal quotes");
+    }
+
     @Test
     void shouldIgnoreNullArguments() {
         CodexCliExecutor executor = new CodexCliExecutor(configFor("/bin/echo"));