sync: cherry-pick changes from feature/3.0.x

Author: loong10k

src/main/java/io/github/easy4j/opencode/HttpCallCancellation.java

@@ -1,11 +1,32 @@
 package io.github.easy4j.opencode;
 
-/** 将业务层取消信号绑定到一次 OpenCode HTTP 调用。 */
+/**
+ * Binds a business-layer cancellation signal to a single OpenCode HTTP call.
+ *
+ * <p>Implementations allow callers to register a cancellation callback that will be invoked
+ * when the underlying HTTP call should be aborted. The {@link #onCancel(Runnable)} method
+ * returns an {@link AutoCloseable} that, when closed, unregisters the callback.</p>
+ *
+ * @author [@Loong Wan](https://github.com/loong10k)
+ * @since 3.0.0
+ * @see io.github.easy4j.opencode.api.OpenCodeHttpClient
+ */
 @FunctionalInterface
 public interface HttpCallCancellation {
 
+    /**
+     * Registers a cancellation callback and returns a handle to unregister it.
+     *
+     * @param callback the runnable to invoke when cancellation is requested
+     * @return an {@link AutoCloseable} that unregisters the callback when closed
+     */
     AutoCloseable onCancel(Runnable callback);
 
+    /**
+     * Returns whether this cancellation has been triggered.
+     *
+     * @return {@code true} if cancellation has been requested, {@code false} otherwise
+     */
     default boolean isCancelled() {
         return false;
     }

src/main/java/io/github/easy4j/opencode/OpenCodeCliConfig.java

@@ -3,10 +3,16 @@
 import lombok.Data;
 
 /**
- * OpenCode 本地 CLI 客户端配置。
- * <p>
- * 涵盖本地 {@code opencode} 可执行文件路径、超时、工作目录等 CLI 运行时设置。
- * </p>
+ * Configuration for the local OpenCode CLI subsystem.
+ *
+ * <p>Covers local {@code opencode} executable path, timeouts, working directory,
+ * and other CLI runtime settings. Can be mapped from Spring
+ * {@code @ConfigurationProperties}.</p>
+ *
+ * @author [@Loong Wan](https://github.com/loong10k)
+ * @since 3.0.0
+ * @see OpenCodeClient
+ * @see OpenCodeClientConfig
  */
 @Data
 public class OpenCodeCliConfig {

src/main/java/io/github/easy4j/opencode/OpenCodeClient.java

@@ -26,29 +26,36 @@
 import java.util.function.Consumer;
 
 /**
- * OpenCode 客户端门面：HTTP Server + SSE 事件流 + 本地 CLI。
- * <p>
- * 三条通信通道相互独立，按各自子配置的 {@code enabled} 决定是否创建：
- * </p>
+ * Facade client for OpenCode: HTTP Server + SSE event stream + local CLI.
+ *
+ * <p>Three communication channels are independent of each other and are created based on
+ * the {@code enabled} flag in their respective sub-configurations:</p>
  * <ul>
- *     <li>{@link OpenCodeHttpClientConfig#isEnabled()} = false → HTTP / SSE 子客户端为 {@code null}</li>
- *     <li>{@link OpenCodeCliConfig#isEnabled()} = false → CLI 子客户端为 {@code null}</li>
+ *     <li>{@link OpenCodeHttpClientConfig#isEnabled()} = false -> HTTP/SSE sub-clients are {@code null}</li>
+ *     <li>{@link OpenCodeCliConfig#isEnabled()} = false -> CLI sub-client is {@code null}</li>
  * </ul>
  *
- * <h3>构造器选择</h3>
- * <p>提供 8 个重载覆盖三类场景：</p>
+ * <h3>Constructor Selection</h3>
+ * <p>Eight overloads cover three scenarios:</p>
  * <ul>
- *     <li>仅 HTTP / 仅 CLI：传入单个子配置，禁用另一子系统</li>
- *     <li>HTTP + CLI：传入两个子配置，子系统都按各自 {@code enabled} 决定</li>
- *     <li>组合配置：传入 {@link OpenCodeClientConfig}，内部拆分为两个子配置</li>
+ *     <li>HTTP only / CLI only: pass a single sub-config; the other subsystem is disabled</li>
+ *     <li>HTTP + CLI: pass two sub-configs; each subsystem is enabled per its own {@code enabled} flag</li>
+ *     <li>Combined config: pass {@link OpenCodeClientConfig}; internally split into two sub-configs</li>
  * </ul>
- * <p>每种场景再分「自动 ObjectMapper/OkHttpClient」与「强制注入」两个变体。
- * 强制注入的版本对 {@code ObjectMapper}/{@code OkHttpClient} 进行 {@code requireNonNull} 校验。</p>
+ * <p>Each scenario has a variant with auto-created ObjectMapper/OkHttpClient and a variant with
+ * forced injection (the injected version applies {@code requireNonNull} validation).</p>
+ *
+ * <h3>Startup Health Checks</h3>
+ * <p>After subsystem initialization, the primary constructor runs health probes based on
+ * {@code startupCheckEnabled} and {@code failFastOnUnavailable} (HTTP: {@code GET /global/health};
+ * CLI: {@code opencode --version}). If the probe fails but fail-fast is not enabled, only a
+ * WARN log is emitted and construction continues.</p>
  *
- * <h3>启动自检</h3>
- * <p>主构造器在子系统初始化后按 {@code startupCheckEnabled} 与 {@code failFastOnUnavailable}
- * 执行健康探测（HTTP：{@code GET /global/health}；CLI：{@code opencode --version}）。
- * 探测失败但未开启 fail-fast 时仅 WARN，不中断构造。</p>
+ * @author [@Loong Wan](https://github.com/loong10k)
+ * @since 3.0.0
+ * @see OpenCodeHttpClientConfig
+ * @see OpenCodeCliConfig
+ * @see OpenCodeClientConfig
  */
 @Slf4j
 public class OpenCodeClient implements AutoCloseable {

src/main/java/io/github/easy4j/opencode/OpenCodeClientConfig.java

@@ -3,11 +3,17 @@
 import lombok.Data;
 
 /**
- * OpenCode 客户端统一配置（纯 POJO，可与 Spring {@code @ConfigurationProperties} 映射）。
- * <p>
- * 组合 {@link OpenCodeHttpClientConfig}（HTTP/Server 相关）与 {@link OpenCodeCliConfig}（本地 CLI 相关），
- * 作为 {@link OpenCodeClient} 等统一入口的配置载体。
- * </p>
+ * Unified configuration POJO for the OpenCode client.
+ *
+ * <p>Composes {@link OpenCodeHttpClientConfig} (HTTP/Server settings) and
+ * {@link OpenCodeCliConfig} (local CLI settings). Compatible with Spring
+ * {@code @ConfigurationProperties} binding.</p>
+ *
+ * @author [@Loong Wan](https://github.com/loong10k)
+ * @since 3.0.0
+ * @see OpenCodeHttpClientConfig
+ * @see OpenCodeCliConfig
+ * @see OpenCodeClient
  */
 @Data
 public class OpenCodeClientConfig {

src/main/java/io/github/easy4j/opencode/OpenCodeHttpClientConfig.java

@@ -3,10 +3,15 @@
 import lombok.Data;
 
 /**
- * OpenCode HTTP Server 客户端配置。
- * <p>
- * 涵盖 Server 根地址、Basic Auth、TLS、HTTP 超时及默认模型等网络相关设置。
- * </p>
+ * Configuration for the OpenCode HTTP Server client.
+ *
+ * <p>Covers server base URL, Basic Auth, TLS, HTTP timeouts, connection pool sizing,
+ * streaming thread pool, and default model/agent settings.</p>
+ *
+ * @author [@Loong Wan](https://github.com/loong10k)
+ * @since 3.0.0
+ * @see OpenCodeHttpClient
+ * @see OpenCodeOkHttpClientFactory
  */
 @Data
 public class OpenCodeHttpClientConfig {

src/main/java/io/github/easy4j/opencode/OpenCodeOkHttpClientFactory.java

@@ -8,9 +8,14 @@
 import java.util.concurrent.TimeUnit;
 
 /**
- * OpenCode 独立运行时使用的 OkHttpClient 工厂。
+ * Factory for creating {@link OkHttpClient} instances used by the OpenCode SDK in standalone mode.
  *
- * <p>Spring 容器已经提供外部 {@link OkHttpClient} 时应使用注入构造器，本工厂不会参与。</p>
+ * <p>When a Spring container already provides an external {@link OkHttpClient}, the injection
+ * constructors should be used instead and this factory will not participate.</p>
+ *
+ * @author [@Loong Wan](https://github.com/loong10k)
+ * @since 3.0.0
+ * @see OpenCodeHttpClientConfig
  */
 public final class OpenCodeOkHttpClientFactory {
 

src/main/java/io/github/easy4j/opencode/api/OpenCodeHttpClient.java

@@ -4,8 +4,8 @@
 import com.fasterxml.jackson.databind.DeserializationFeature;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import io.github.easy4j.opencode.OpenCodeHttpClientConfig;
-import io.github.easy4j.opencode.OpenCodeOkHttpClientFactory;
 import io.github.easy4j.opencode.HttpCallCancellation;
+import io.github.easy4j.opencode.OpenCodeOkHttpClientFactory;
 import io.github.easy4j.opencode.api.model.*;
 import io.github.easy4j.opencode.exception.OpenCodeHttpException;
 import lombok.extern.slf4j.Slf4j;
@@ -22,9 +22,16 @@
 import java.util.Optional;
 
 /**
- * OpenCode Server HTTP 客户端，封装 REST API。
- * <p>基于 OkHttp，支持外部传入 {@link OkHttpClient}（复用别的插件实例）。</p>
+ * HTTP client for the OpenCode Server REST API.
+ *
+ * <p>Built on OkHttp; supports externally provided {@link OkHttpClient} instances for
+ * connection pooling across plugins. All methods throw {@link io.github.easy4j.opencode.exception.OpenCodeHttpException}
+ * on HTTP errors.</p>
  *
+ * @author [@Loong Wan](https://github.com/loong10k)
+ * @since 3.0.0
+ * @see OpenCodeHttpClientConfig
+ * @see io.github.easy4j.opencode.exception.OpenCodeHttpException
  * @see <a href="https://opencode.ai/docs/server/">opencode server docs</a>
  */
 @Slf4j
@@ -36,14 +43,12 @@ public class OpenCodeHttpClient implements AutoCloseable {
     private final OpenCodeHttpClientConfig config;
     private final OkHttpClient httpClient;
     private final ObjectMapper objectMapper;
-    private final boolean ownsHttpClient;
 
     public OpenCodeHttpClient(OpenCodeHttpClientConfig config, ObjectMapper objectMapper, OkHttpClient httpClient) {
         this.config = Objects.requireNonNull(config, "config");
         this.objectMapper = Objects.isNull(objectMapper) ? new ObjectMapper()
                 .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false): objectMapper;
-        this.ownsHttpClient = Objects.isNull(httpClient);
-        this.httpClient = this.ownsHttpClient ? buildOkHttpClient(config) : httpClient;
+        this.httpClient = Objects.isNull(httpClient) ? buildOkHttpClient(config) : httpClient;
     }
 
     private static OkHttpClient buildOkHttpClient(OpenCodeHttpClientConfig config) {
@@ -932,16 +937,6 @@ private String toJson(Object body) {
 
     @Override
     public void close() {
-        if (ownsHttpClient) {
-            httpClient.dispatcher().executorService().shutdownNow();
-            httpClient.connectionPool().evictAll();
-            if (Objects.nonNull(httpClient.cache())) {
-                try {
-                    httpClient.cache().close();
-                } catch (IOException error) {
-                    log.debug("Failed to close OpenCode HTTP cache", error);
-                }
-            }
-        }
+        // 外部传入的 OkHttpClient 不关闭；自建的也不主动关闭（OkHttpClient 内部管理连接池）
     }
 }

src/main/java/io/github/easy4j/opencode/api/OpenCodeSseClient.java

@@ -25,8 +25,16 @@
 import java.util.function.Consumer;
 
 /**
- * OpenCode Server SSE 客户端，消费 {@code GET /event} 事件流。
- * <p>基于 OkHttp {@link EventSources}，支持外部传入 {@link OkHttpClient}。</p>
+ * SSE client for the OpenCode Server event stream ({@code GET /event}).
+ *
+ * <p>Built on OkHttp {@link EventSources}; supports externally provided {@link OkHttpClient}
+ * instances. Provides both callback-based and blocking-queue-based subscription models,
+ * as well as session-scoped and type-filtered subscriptions.</p>
+ *
+ * @author [@Loong Wan](https://github.com/loong10k)
+ * @since 3.0.0
+ * @see OpenCodeHttpClientConfig
+ * @see io.github.easy4j.opencode.api.event.EventHandler
  */
 @Slf4j
 public class OpenCodeSseClient implements AutoCloseable {

src/main/java/io/github/easy4j/opencode/api/event/EventHandler.java

@@ -5,16 +5,22 @@
 import java.util.Map;
 
 /**
- * opencode SSE 事件回调处理器，提供类型化默认方法。
- * <p>使用方式：</p>
+ * Typed callback handler for OpenCode SSE events.
+ *
+ * <p>All methods have no-op defaults; callers override only the callbacks they care about.</p>
+ *
+ * <p>Usage example:</p>
  * <pre>{@code
  * client.onSessionEvent(sessionId, new EventHandler() {
  *     public void onTextDelta(String delta, Event event) {
  *         System.out.print(delta);
  *     }
  * });
  * }</pre>
- * 所有方法默认 no-op；调用方按需覆写关心的回调。
+ *
+ * @author [@Loong Wan](https://github.com/loong10k)
+ * @since 3.0.0
+ * @see io.github.easy4j.opencode.api.OpenCodeSseClient
  */
 public interface EventHandler {
 

src/main/java/io/github/easy4j/opencode/api/mapper/OpenCodeCallbackParser.java

@@ -12,12 +12,23 @@
 import java.util.regex.Pattern;
 
 /**
- * 从 OpenCode AI 响应中解析回调 JSON。
- * <p>
- * OpenCode 没有原生的 webhook/callback 机制。
- * 本解析器尝试从 AI 的文本响应中提取 JSON 块，
- * 其格式由 cloud-agents 的 prompt 模板约定（如 SKILL.md 中定义的 callback_url 输出格式）。
- * </p>
+ * Parses callback JSON from OpenCode AI text responses.
+ *
+ * <p>OpenCode does not have a native webhook/callback mechanism. This parser attempts
+ * to extract JSON blocks from the AI's text response, following the format conventions
+ * defined by cloud-agents prompt templates (e.g., the callback_url output format
+ * specified in SKILL.md).</p>
+ *
+ * <p>The parser tries three strategies in order:</p>
+ * <ol>
+ *     <li>Extract JSON from {@code ```json ... ```} fenced code blocks</li>
+ *     <li>Parse the entire text as JSON directly</li>
+ *     <li>Extract bare JSON objects containing {@code task_id}, {@code taskId}, or {@code title}</li>
+ * </ol>
+ *
+ * @author [@Loong Wan](https://github.com/loong10k)
+ * @since 3.0.0
+ * @see io.github.easy4j.opencode.api.model.PromptResult
  */
 public class OpenCodeCallbackParser {