easy-4-java
diff --git a/‎README.md‎
Lines changed: 89 additions & 28 deletions b/‎README.md‎
Lines changed: 89 additions & 28 deletions
@@ -4,9 +4,11 @@
 
 [![Java](https://img.shields.io/badge/Java-21-orange)](https://github.com/easy-4-java/codex-java-sdk) [![License](https://img.shields.io/badge/license-Apache%202.0-green)](https://www.apache.org/licenses/LICENSE-2.0.txt)
 
-> Java SDK for the [Codex CLI](https://github.com/openai/codex): subprocess
-> integration that drives the local `codex` agent (exec, interactive sessions,
-> session resume / fork / archive, doctor, review) from Java.
+> Java SDK for the [Codex CLI](https://github.com/openai/codex) with two
+> integration routes: a subprocess wrapper that drives the local `codex`
+> agent (exec, interactive sessions, session resume / fork / archive, doctor,
+> review), and a JSON-RPC 2.0 over WebSocket client for a remote Codex
+> app-server (`thread/start` → `turn/start` → notification stream).
 
 ## Table of Contents
 
@@ -24,10 +26,14 @@
 
 ## 1. Project Overview
 
-`codex-java-sdk` lets Java applications run the
-[Codex CLI](https://github.com/openai/codex) agent (`codex`) as a local subprocess.
-It is a **CLI wrapper**, not a direct OpenAI API client — every call maps to a real
-`codex` command line invocation.
+`codex-java-sdk` lets Java applications integrate the
+[Codex CLI](https://github.com/openai/codex) agent (`codex`) through two
+routes. Neither route is a direct OpenAI API client.
+
+- **CLI route (local subprocess)** — every call maps to a real `codex`
+  command line invocation.
+- **App-server route (remote long connection)** — a JSON-RPC 2.0 over
+  WebSocket client for a running Codex app-server.
 
 The SDK covers:
 
@@ -38,11 +44,16 @@ The SDK covers:
 - **Parsed models** — `CodexEvent` (JSONL events), `CodexSession`, `CodexDoctorReport`.
 - **Utilities** — `doctor`, `review`, `login` / `logout`, MCP management, `update`,
   `features`, shell `completion`.
+- **App-server WebSocket route** — `CodexAppServerClient` with per-turn
+  connections, `thread/start` / `thread/resume` reuse via a bounded
+  `sessionKey → threadId` LRU, streaming agent-message deltas and
+  `turn/completed` finalization.
 
 What it is **not**:
 
 - Not an OpenAI API client (no direct HTTP calls to the OpenAI API).
-- Not a replacement for the `codex` binary — the CLI must be installed and runnable.
+- Not a replacement for the `codex` binary — the CLI must be installed and runnable
+  (local route), or a Codex app-server must be reachable (WebSocket route).
 
 Typical scenarios:
 
@@ -53,6 +64,7 @@ Typical scenarios:
 | Long-running interactive agent | `startSession(prompt)` / `resumeSession(sessionId)` |
 | Reproduce a session in a sandbox | `forkSession(sessionId)` / `execResume(sessionId, prompt)` |
 | Environment diagnostics | `doctorSummary()` / `doctorJson()` |
+| Remote agent with session continuity | `CodexAppServerClient.runTurn(request)` with `sessionKey` |
 
 ## 2. Features & Status
 
@@ -65,18 +77,20 @@ Typical scenarios:
 | Session lifecycle | Active development | `resumeSession`, `resumeLastSession`, `forkSession`, `forkLastSession`, `archiveSession`, `unarchiveSession`, `execResume` |
 | Doctor & review | Active development | `doctor`, `doctorJson`, `doctorSummary`, `review`, `reviewCommit`, `reviewBase` |
 | Auth / MCP / misc | Active development | `login`, `logout`, `mcpList` / `mcpAdd` / `mcpGet` / `mcpRemove`, `update`, `features`, `completion`, `app` |
-| Config model | Active development | `CodexClientConfig` POJO (plain, Spring-bindable) |
+| App-server WebSocket route | Active development | `CodexAppServerClient.runTurn` / `runTurnAsync`, `thread/start` / `thread/resume`, agent-message deltas, `sessionKey → threadId` LRU (1000) |
+| Config model | Active development | `CodexClientConfig` POJO (plain, Spring-bindable), `CodexAppServerConfig` POJO |
 
-> **Assumption**: the capability statuses above reflect the current state of the
-> 1.0.x branch; the module is under active development.
+> **Assumption**: the capability statuses above reflect the current state of
+> the active branch; the module is under active development.
 
 ## 3. Requirements & Compatibility
 
 | Requirement | Version / Notes |
 | :--- | :--- |
 | JDK | 21+ |
 | Maven | 3.0+ (enforced; Maven Wrapper `./mvnw` included) |
-| Codex CLI | `codex` must be installed and available (`localExecutable` configures the path) |
+| Codex CLI | Local route: `codex` must be installed and available (`localExecutable` configures the path) |
+| Codex app-server | WebSocket route only: a reachable app-server (`baseUrl` accepts ws/wss/http/https) |
 
 Version lines:
 
@@ -89,35 +103,39 @@ Version lines:
 ## 4. Architecture & Modules
 
 ```text
-+------------------+   +------------------------------------------+
-| Java application |   | codex-java-sdk                            |
-|                  |-->|  CodexClient (facade)                    |
-| prompt / options |   |    | CodexCli (command mapping)          |
-|                  |   |    |   | CodexCliExecutor                |
-|                  |   |    |   |   `codex` child process         |
-|                  |   |    |   CodexCliResult                    |
-+------------------+   |    | CodexEvent/CodexSession/DoctorReport|
-                       +-------------------+----------------------+
++------------------+   +---------------------------------------------+
+| Java application |   | codex-java-sdk                               |
+|                  |-->|  Route 1 (local): CodexClient (facade)       |
+| prompt / options |   |    | CodexCli (command mapping)             |
+|                  |   |    |   | CodexCliExecutor                   |
+|                  |   |    |   |   `codex` child process            |
+|                  |   |    |   CodexCliResult                       |
+|                  |   |  Route 2 (remote): CodexAppServerClient      |
+|                  |   |    | JSON-RPC 2.0 over WebSocket            |
+|                  |   |    | thread/start -> turn/start -> events   |
+|                  |   | CodexEvent/CodexSession/CodexDoctorReport    |
++------------------+   +-------------------+-------------------------+
                                            |
                                            v
                      +-------------------------------------------+
-                     | Local `codex` CLI (exec, session, doctor, |
-                     | review, login, ...)                       |
+                     | Local `codex` CLI (route 1) or remote     |
+                     | Codex app-server (route 2)                |
                      +-------------------------------------------+
 ```
 
 Single-module Maven project (`packaging: jar`). No child modules.
 
 | Artifact | Responsibility |
 | :--- | :--- |
-| `io.github.easy4j:codex-java-sdk` | CLI facade, command mapping, subprocess executor, result & parsed models |
+| `io.github.easy4j:codex-java-sdk` | CLI facade, command mapping, subprocess executor, WebSocket app-server client, results & parsed models |
 
 Key packages:
 
-| Package | Content |
+| Package | Contents |
 | :--- | :--- |
 | `io.github.easy4j.codex` | `CodexClient`, `CodexClientConfig` |
 | `io.github.easy4j.codex.cli` | `CodexCli`, `CodexCliExecutor`, `CodexCliResult` |
+| `io.github.easy4j.codex.appserver` | `CodexAppServerClient`, `CodexAppServerConfig`, `AppServerTurnRequest`, `AppServerTurnResult`, `ThreadMappingCache`, `CodexAppServerException` |
 | `io.github.easy4j.codex.model` | `CodexEvent`, `CodexSession`, `CodexDoctorReport` |
 
 ## 5. Installation
@@ -197,6 +215,19 @@ There is no configuration file of its own. Key fields:
 | `strictConfig` | boolean | `false` | Fail on unknown config fields |
 | `enable` / `disable` | String[] | - | Features to enable / disable |
 
+### 7.1 `CodexAppServerConfig` (app-server WebSocket route)
+
+Plain POJO (Spring `@ConfigurationProperties`-bindable). Field names mirror the
+commonly used `CodexEndpoint` binding:
+
+| Field | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `baseUrl` | String | - | App-server base URL (`ws://`/`wss://` as-is, `http://`/`https://` upgraded) |
+| `token` | String | - | Bearer token sent as `Authorization: Bearer <token>` on the handshake |
+| `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 |
+
 ## 8. Core Usage / API
 
 ### 8.1 JSONL events
@@ -222,6 +253,36 @@ try (CodexClient client = new CodexClient(config)) {
 }
 ```
 
+### 8.3 App-server WebSocket route (remote Codex)
+
+```java
+import io.github.easy4j.codex.appserver.AppServerTurnRequest;
+import io.github.easy4j.codex.appserver.AppServerTurnResult;
+import io.github.easy4j.codex.appserver.CodexAppServerClient;
+import io.github.easy4j.codex.appserver.CodexAppServerConfig;
+
+CodexAppServerConfig config = new CodexAppServerConfig();
+config.setBaseUrl("ws://codex-host:8081");   // http(s) is upgraded to ws(s) automatically
+config.setToken("capability-token");
+config.setReadTimeoutMillis(120_000);
+
+try (CodexAppServerClient client = new CodexAppServerClient(config)) {
+    AppServerTurnResult result = client.runTurn(AppServerTurnRequest.builder()
+            .prompt("Fix the failing test")
+            .sessionKey("chat-42")                                  // enables thread/resume reuse
+            .onDelta(delta -> System.out.print(delta))              // agentMessage deltas, in order
+            .build());
+    System.out.println(result.getThreadId() + " -> " + result.getContent());
+}
+```
+
+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
+and never interrupt the turn. Failures — connection, JSON-RPC error,
+`turn/failed`, `error`, premature close or read timeout — surface as
+`CodexAppServerException`.
+
 ## 9. Testing & Build
 
 ```bash
@@ -230,9 +291,9 @@ try (CodexClient client = new CodexClient(config)) {
 
 - The build is configured with the JaCoCo Maven plugin (report + `check` goal with a
   90% line-coverage rule bound to the `verify` phase; `haltOnFailure=false`).
-- **Assumption**: the 1.0.x branch currently checks in no test sources under
-  `src/test`; coverage thresholds are therefore enforced only when tests exist.
-- No CI workflow files are present under `.github/` in this worktree.
+- The active branch ships a full test suite (206 tests on `feature/3.0.x`), including
+  end-to-end WebSocket contract tests against an in-process fake app-server.
+- CI workflow: `.github/workflows/ci.yml`.
 
 ## 10. Versioning & Branches