Package io.github.easy4j.opencode.api

Class OpenCodeHttpClient

java.lang.Object
io.github.easy4j.opencode.api.OpenCodeHttpClient
All Implemented Interfaces:
AutoCloseable
Direct Known Subclasses:
OpenCodeChatClient
public class OpenCodeHttpClient extends Object implements AutoCloseable
HTTP client for the OpenCode Server REST API.

Built on OkHttp; supports externally provided OkHttpClient instances for connection pooling across plugins. All methods throw OpenCodeHttpException on HTTP errors.

Since:
1.0.0
Author:
Loong Wan
See Also:

  • Constructor Details

    • OpenCodeHttpClient

      public OpenCodeHttpClient(OpenCodeHttpClientConfig config, com.fasterxml.jackson.databind.ObjectMapper objectMapper, okhttp3.OkHttpClient httpClient)
      创建 open code http client 实例，并按传入依赖确定资源所有权。
      Parameters:
      config - 客户端配置；不得为 null
      objectMapper - JSON 映射器；为 null 时使用 SDK 默认配置
      httpClient - 可复用的 OkHttp 客户端；为 null 时由 SDK 创建

  • Method Details

    • health

      public HealthStatus health()
      同步查询 OpenCode Server 的健康状态和版本信息。
      Returns:
      OpenCode SDK 返回的健康状态对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • healthAsync

      public CompletableFuture<HealthStatus> healthAsync()
      异步检查 OpenCode Server 健康状态。
      Returns:
      异步结果；失败时以异常方式完成

    • createSession

      public Session createSession(String title)
      通过 OpenCode Server HTTP API 创建会话。
      Parameters:
      title - 会话标题；用于展示和稳定会话查找
      Returns:
      OpenCode SDK 返回的会话对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • createSession

      public Session createSession(String title, OpenCodeRequestContext context)
      通过 OpenCode Server HTTP API 创建会话。
      Parameters:
      title - 会话标题；用于展示和稳定会话查找
      context - 请求上下文；为 null 时不附加目录头
      Returns:
      OpenCode SDK 返回的会话对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • createSession

      public Session createSession(String title, OpenCodeRequestContext context, HttpCallCancellation cancellation)
      通过 OpenCode Server HTTP API 创建会话。
      Parameters:
      title - 会话标题；用于展示和稳定会话查找
      context - 请求上下文；为 null 时不附加目录头
      cancellation - 取消信号；为 null 时不可由外部取消
      Returns:
      OpenCode SDK 返回的会话对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • createSessionAsync

      public CompletableFuture<Session> createSessionAsync(String title, OpenCodeRequestContext context, HttpCallCancellation cancellation)
      异步请求 OpenCode Server 创建会话；网络或解析失败通过返回的 Future 传播。
      Parameters:
      title - 会话标题；用于展示和稳定会话查找
      context - 请求上下文；为 null 时不附加目录头
      cancellation - 取消信号；为 null 时不可由外部取消
      Returns:
      异步结果；失败时以异常方式完成

    • getSession

      public Session getSession(String sessionId)
      通过 OpenCode Server HTTP API 获取会话。
      Parameters:
      sessionId - OpenCode 会话 ID；不得为空
      Returns:
      OpenCode SDK 返回的会话对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • listSessions

      public List<Session> listSessions()
      通过 OpenCode Server HTTP API 查询会话；无数据时返回空集合。
      Returns:
      OpenCode Server 返回的会话列表；无数据时为空列表
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • listSessions

      public List<Session> listSessions(String search, Integer limit, Integer start)
      分页/过滤列出 sessions，对齐 Hermes listSessions(limit, offset, source, includeChildren)。
      Parameters:
      search - 标题搜索条件；为空时不限制
      limit - 最大返回数量；为 null 时使用服务端默认值
      start - 分页起始偏移；为 null 时从首项开始
      Returns:
      OpenCode Server 返回的会话列表；无数据时为空列表
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • listSessions

      public List<Session> listSessions(String search, Integer limit, Integer start, OpenCodeRequestContext context)
      通过 OpenCode Server HTTP API 查询会话；无数据时返回空集合。
      Parameters:
      search - 标题搜索条件；为空时不限制
      limit - 最大返回数量；为 null 时使用服务端默认值
      start - 分页起始偏移；为 null 时从首项开始
      context - 请求上下文；为 null 时不附加目录头
      Returns:
      OpenCode Server 返回的会话列表；无数据时为空列表
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • listSessionsAsync

      public CompletableFuture<List<Session>> listSessionsAsync(String search, Integer limit, Integer start, OpenCodeRequestContext context, HttpCallCancellation cancellation)
      异步分页列出会话。
      Parameters:
      search - 标题搜索条件；为空时不限制
      limit - 最大返回数量；为 null 时使用服务端默认值
      start - 分页起始偏移；为 null 时从首项开始
      context - 请求上下文；为 null 时不附加目录头
      cancellation - 取消信号；为 null 时不可由外部取消
      Returns:
      异步结果；失败时以异常方式完成

    • findSessionByTitle

      public Optional<Session> findSessionByTitle(String title)
      按 title 精确查找 session。
      Parameters:
      title - 会话标题；用于展示和稳定会话查找
      Returns:
      匹配的 OpenCode 会话；未找到时为 Optional.empty()
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • findSessionByTitle

      public Optional<Session> findSessionByTitle(String title, OpenCodeRequestContext context)
      调用 OpenCode Server 搜索接口查找标题匹配的会话；未命中时返回空结果。
      Parameters:
      title - 会话标题；用于展示和稳定会话查找
      context - 请求上下文；为 null 时不附加目录头
      Returns:
      匹配的 OpenCode 会话；未找到时为 Optional.empty()
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • findSessionByTitle

      public Optional<Session> findSessionByTitle(String title, OpenCodeRequestContext context, HttpCallCancellation cancellation)
      调用 OpenCode Server 搜索接口查找标题匹配的会话；未命中时返回空结果。
      Parameters:
      title - 会话标题；用于展示和稳定会话查找
      context - 请求上下文；为 null 时不附加目录头
      cancellation - 取消信号；为 null 时不可由外部取消
      Returns:
      匹配的 OpenCode 会话；未找到时为 Optional.empty()
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • deleteSession

      public boolean deleteSession(String sessionId)
      请求 OpenCode Server 删除会话。
      Parameters:
      sessionId - OpenCode 会话 ID；不得为空
      Returns:
      操作成功返回 true，否则返回 false
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • prompt

      public PromptResult prompt(String sessionId, PromptRequest request)
      向指定会话同步提交 Prompt，并等待 OpenCode Server 返回完整生成结果。
      Parameters:
      sessionId - OpenCode 会话 ID；不得为空
      request - 请求对象；不得为 null
      Returns:
      OpenCode SDK 返回的Prompt 结果对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • prompt

      public PromptResult prompt(String sessionId, PromptRequest request, HttpCallCancellation cancellation)
      向指定会话同步提交 Prompt，并等待 OpenCode Server 返回完整生成结果。
      Parameters:
      sessionId - OpenCode 会话 ID；不得为空
      request - 请求对象；不得为 null
      cancellation - 取消信号；为 null 时不可由外部取消
      Returns:
      OpenCode SDK 返回的Prompt 结果对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • promptCompletionAsync

      public CompletableFuture<PromptResult> promptCompletionAsync(String sessionId, PromptRequest request, HttpCallCancellation cancellation)
      异步发送消息并等待完整 Prompt 结果。
      Parameters:
      sessionId - OpenCode 会话 ID；不得为空
      request - 请求对象；不得为 null
      cancellation - 取消信号；为 null 时不可由外部取消
      Returns:
      异步结果；失败时以异常方式完成

    • chatCompletionWithSession

      public PromptResult chatCompletionWithSession(PromptRequest request, String sessionKey)
      复用或创建稳定会话后提交聊天请求并返回结果。
      Parameters:
      request - 请求对象；不得为 null
      sessionKey - 用于稳定复用会话的业务键；相同键映射到同一标题
      Returns:
      OpenCode SDK 返回的Prompt 结果对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • chatCompletionWithSession

      public PromptResult chatCompletionWithSession(PromptRequest request, String sessionKey, HttpCallCancellation cancellation)
      复用或创建稳定会话后提交聊天请求并返回结果。
      Parameters:
      request - 请求对象；不得为 null
      sessionKey - 用于稳定复用会话的业务键；相同键映射到同一标题
      cancellation - 取消信号；为 null 时不可由外部取消
      Returns:
      OpenCode SDK 返回的Prompt 结果对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • chatCompletionWithSessionAsync

      public CompletableFuture<Boolean> chatCompletionWithSessionAsync(PromptRequest request, String sessionKey)
      异步复用或创建稳定会话后提交聊天请求，不阻塞调用线程。
      Parameters:
      request - 请求对象；不得为 null
      sessionKey - 用于稳定复用会话的业务键；相同键映射到同一标题
      Returns:
      异步结果；失败时以异常方式完成

    • ensureSession

      public String ensureSession(String sessionKey)
      查找稳定会话键对应的会话；不存在时创建新会话。
      Parameters:
      sessionKey - 用于稳定复用会话的业务键；相同键映射到同一标题
      Returns:
      已复用或新建的 OpenCode 会话 ID
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • ensureSession

      public String ensureSession(String sessionKey, OpenCodeRequestContext context)
      查找稳定会话键对应的会话；不存在时创建新会话。
      Parameters:
      sessionKey - 用于稳定复用会话的业务键；相同键映射到同一标题
      context - 请求上下文；为 null 时不附加目录头
      Returns:
      已复用或新建的 OpenCode 会话 ID
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • ensureSession

      public String ensureSession(String sessionKey, OpenCodeRequestContext context, HttpCallCancellation cancellation)
      查找稳定会话键对应的会话；不存在时创建新会话。
      Parameters:
      sessionKey - 用于稳定复用会话的业务键；相同键映射到同一标题
      context - 请求上下文；为 null 时不附加目录头
      cancellation - 取消信号；为 null 时不可由外部取消
      Returns:
      已复用或新建的 OpenCode 会话 ID
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • ensureSessionAsync

      public CompletableFuture<String> ensureSessionAsync(String sessionKey, OpenCodeRequestContext context, HttpCallCancellation cancellation)
      异步查找或创建会话。
      Parameters:
      sessionKey - 用于稳定复用会话的业务键；相同键映射到同一标题
      context - 请求上下文；为 null 时不附加目录头
      cancellation - 取消信号；为 null 时不可由外部取消
      Returns:
      异步结果；失败时以异常方式完成

    • promptAsync

      public CompletableFuture<Boolean> promptAsync(String sessionId, PromptRequest request)
      向指定会话提交无需等待正文的异步 Prompt 请求。
      Parameters:
      sessionId - OpenCode 会话 ID；不得为空
      request - 请求对象；不得为 null
      Returns:
      异步结果；失败时以异常方式完成

    • promptAsync

      public CompletableFuture<Boolean> promptAsync(String sessionId, PromptRequest request, OpenCodeRequestContext context)
      向指定会话提交无需等待正文的异步 Prompt 请求。
      Parameters:
      sessionId - OpenCode 会话 ID；不得为空
      request - 请求对象；不得为 null
      context - 请求上下文；为 null 时不附加目录头
      Returns:
      异步结果；失败时以异常方式完成

    • getMessages

      public List<PromptResult> getMessages(String sessionId)
      通过 OpenCode Server HTTP API 获取会话消息。
      Parameters:
      sessionId - OpenCode 会话 ID；不得为空
      Returns:
      OpenCode Server 返回的Prompt 结果列表；无数据时为空列表
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • abortSession

      public boolean abortSession(String sessionId)
      请求 OpenCode Server 中止指定会话中正在运行的生成任务。
      Parameters:
      sessionId - OpenCode 会话 ID；不得为空
      Returns:
      操作成功返回 true，否则返回 false
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • listAgents

      public List<Agent> listAgents()
      通过 OpenCode Server HTTP API 查询智能体；无数据时返回空集合。
      Returns:
      OpenCode Server 返回的智能体列表；无数据时为空列表
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • getConfig

      public OpenCodeConfig getConfig()
      GET /config，获取实例生效的配置。
      Returns:
      OpenCode SDK 返回的配置对象

    • getGlobalConfig

      public OpenCodeConfig getGlobalConfig()
      GET /global/config，获取全局配置。
      Returns:
      OpenCode SDK 返回的配置对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • updateConfig

      public OpenCodeConfig updateConfig(Object body)
      PATCH /config，更新实例配置。
      Parameters:
      body - 提交给服务端的请求体
      Returns:
      OpenCode SDK 返回的配置对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • updateGlobalConfig

      public OpenCodeConfig updateGlobalConfig(Object body)
      PATCH /global/config，更新全局配置。
      Parameters:
      body - 提交给服务端的请求体
      Returns:
      OpenCode SDK 返回的配置对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • getConfigProviders

      public ProviderList getConfigProviders()
      GET /config/providers，获取已配置的 providers 列表与默认模型映射。
      Returns:
      OpenCode SDK 返回的模型提供方清单对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • listProjects

      public List<Project> listProjects()
      GET /project，列出所有已知项目。
      Returns:
      OpenCode Server 返回的项目列表；无数据时为空列表
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • getCurrentProject

      public Project getCurrentProject()
      GET /project/current，获取当前项目。
      Returns:
      OpenCode SDK 返回的项目对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • updateProject

      public Project updateProject(String projectId, Object body)
      PATCH /project/:id，更新项目（name / icon / commands 等）。
      Parameters:
      projectId - OpenCode 项目 ID；不得为空
      body - 提交给服务端的请求体
      Returns:
      OpenCode SDK 返回的项目对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • initProjectGit

      public boolean initProjectGit()
      POST /project/git/init，为当前项目初始化 git 仓库。
      Returns:
      操作成功返回 true，否则返回 false
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • listProviders

      public ProviderList listProviders()
      GET /provider，获取 providers 列表 + 默认 provider/model 映射 + 已连接 provider。
      Returns:
      OpenCode SDK 返回的模型提供方清单对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • listProviderAuthMethods

      public Map<String,List<ProviderAuthMethod>> listProviderAuthMethods()
      GET /provider/auth，获取每个 provider 的可用认证方式。
      Returns:
      OpenCode Server 返回的键值映射；无数据时为空映射
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • providerOAuthAuthorize

      public ProviderAuthAuthorization providerOAuthAuthorize(String providerId, String method)
      POST /provider/:id/oauth/authorize，启动 provider OAuth 授权。
      Parameters:
      providerId - 模型提供方 ID
      method - 认证或升级方式
      Returns:
      OpenCode SDK 返回的模型提供方授权信息对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • providerOAuthCallback

      public boolean providerOAuthCallback(String providerId, String code)
      POST /provider/:id/oauth/callback，处理 OAuth 回调。
      Parameters:
      providerId - 模型提供方 ID
      code - OAuth 回调授权码
      Returns:
      操作成功返回 true，否则返回 false
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • providerOAuthCallbackAsync

      public CompletableFuture<Boolean> providerOAuthCallbackAsync(String providerId, String code)
      异步处理 provider OAuth 回调。
      Parameters:
      providerId - 模型提供方 ID
      code - OAuth 回调授权码
      Returns:
      异步结果；失败时以异常方式完成

    • listFiles

      public List<FileNode> listFiles(String path)
      GET /file，列出指定目录下的文件/目录树。
      Parameters:
      path - 文件或工作目录路径
      Returns:
      OpenCode Server 返回的文件节点列表；无数据时为空列表
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • getFileContent

      public FileContent getFileContent(String path)
      GET /file/content，读取文件内容。
      Parameters:
      path - 文件或工作目录路径
      Returns:
      OpenCode SDK 返回的文件内容对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • getFileStatus

      public List<FileNode> getFileStatus()
      GET /file/status，获取项目所有文件的 git 状态。
      Returns:
      OpenCode Server 返回的文件节点列表；无数据时为空列表
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • find

      public List<FileSearchResult> find(String pattern)
      GET /find，ripgrep 文本搜索。
      Parameters:
      pattern - 文本搜索模式
      Returns:
      OpenCode Server 返回的文件搜索匹配项列表；无数据时为空列表
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • findFiles

      public List<String> findFiles(String query)
      GET /find/file，按文件名/模式查找文件。
      Parameters:
      query - 搜索或数据库查询表达式
      Returns:
      OpenCode Server 返回的文本列表；无数据时为空列表
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • findSymbols

      public List<Symbol> findSymbols(String query)
      GET /find/symbol，通过 LSP 搜索工作区符号。
      Parameters:
      query - 搜索或数据库查询表达式
      Returns:
      OpenCode Server 返回的代码符号列表；无数据时为空列表
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • listCommands

      public List<Command> listCommands()
      GET /command，列出已注册的 slash commands。
      Returns:
      OpenCode Server 返回的斜杠命令列表；无数据时为空列表
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • listSkills

      public List<Skill> listSkills()
      GET /skill，列出已注册的 skills。
      Returns:
      OpenCode Server 返回的技能描述列表；无数据时为空列表
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • listFormatters

      public List<FormatterStatus> listFormatters()
      GET /formatter，列出 formatter 状态。
      Returns:
      OpenCode Server 返回的格式化器状态列表；无数据时为空列表
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • listLsps

      public List<LspStatus> listLsps()
      GET /lsp，列出 LSP 服务器状态。
      Returns:
      OpenCode Server 返回的语言服务器状态列表；无数据时为空列表
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • listMcpServers

      public Map<String,McpStatus> listMcpServers()
      GET /mcp，列出 MCP 服务器状态。
      Returns:
      OpenCode Server 返回的键值映射；无数据时为空映射
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • addMcpServer

      public McpStatus addMcpServer(String name, Object config)
      POST /mcp，动态添加 MCP server。
      Parameters:
      name - 资源名称
      config - 客户端配置；不得为 null
      Returns:
      OpenCode SDK 返回的MCP 服务状态对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • getPath

      public OpenCodePath getPath()
      GET /path，获取 opencode 工作目录相关的所有路径。
      Returns:
      OpenCode SDK 返回的运行路径对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • getVcs

      public VcsInfo getVcs()
      GET /vcs，获取当前工作目录的 VCS 信息。
      Returns:
      OpenCode SDK 返回的版本控制信息对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • getSessionStatusMap

      public Map<String,SessionStatus> getSessionStatusMap()
      GET /session/status，获取所有 session 状态。
      Returns:
      OpenCode Server 返回的键值映射；无数据时为空映射
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • getSessionChildren

      public List<Session> getSessionChildren(String sessionId)
      GET /session/:id/children，列出 session 的子（forked）session。
      Parameters:
      sessionId - OpenCode 会话 ID；不得为空
      Returns:
      OpenCode Server 返回的会话列表；无数据时为空列表
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • getSessionTodo

      public List<SessionTodo> getSessionTodo(String sessionId)
      GET /session/:id/todo，获取 session 的 todo 列表。
      Parameters:
      sessionId - OpenCode 会话 ID；不得为空
      Returns:
      OpenCode Server 返回的会话待办项列表；无数据时为空列表
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • getSessionDiff

      public List<FileDiff> getSessionDiff(String sessionId, String messageId)
      GET /session/:id/diff，获取指定 message 之后的文件 diff。
      Parameters:
      sessionId - OpenCode 会话 ID；不得为空
      messageId - 会话消息 ID
      Returns:
      OpenCode Server 返回的文件差异列表；无数据时为空列表
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • shareSession

      public Session shareSession(String sessionId)
      POST /session/:id/share，创建可分享链接。
      Parameters:
      sessionId - OpenCode 会话 ID；不得为空
      Returns:
      OpenCode SDK 返回的会话对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • unshareSession

      public Session unshareSession(String sessionId)
      DELETE /session/:id/share，取消分享。
      Parameters:
      sessionId - OpenCode 会话 ID；不得为空
      Returns:
      OpenCode SDK 返回的会话对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • forkSession

      public Session forkSession(String sessionId, String messageId)
      POST /session/:id/fork，从指定 message 处 fork session。
      Parameters:
      sessionId - OpenCode 会话 ID；不得为空
      messageId - 会话消息 ID
      Returns:
      OpenCode SDK 返回的会话对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • initSession

      public boolean initSession(String sessionId, String messageId, String providerId, String modelId)
      POST /session/:id/init，用首个 message 初始化 session（创建 AGENTS.md）。
      Parameters:
      sessionId - OpenCode 会话 ID；不得为空
      messageId - 会话消息 ID
      providerId - 模型提供方 ID
      modelId - 模型 ID
      Returns:
      操作成功返回 true，否则返回 false
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • summarizeSession

      public boolean summarizeSession(String sessionId, String providerId, String modelId)
      POST /session/:id/summarize，对 session 进行 AI 摘要压缩。
      Parameters:
      sessionId - OpenCode 会话 ID；不得为空
      providerId - 模型提供方 ID
      modelId - 模型 ID
      Returns:
      操作成功返回 true，否则返回 false
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • revertSession

      public boolean revertSession(String sessionId, String messageId, String partId)
      POST /session/:id/revert，回退到指定 message（可指定 part）。
      Parameters:
      sessionId - OpenCode 会话 ID；不得为空
      messageId - 会话消息 ID
      partId - 消息片段 ID
      Returns:
      操作成功返回 true，否则返回 false
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • unrevertSession

      public boolean unrevertSession(String sessionId)
      POST /session/:id/unrevert，撤销回退。
      Parameters:
      sessionId - OpenCode 会话 ID；不得为空
      Returns:
      操作成功返回 true，否则返回 false
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • getMessage

      public MessageInfo getMessage(String sessionId, String messageId)
      GET /session/:id/message/:messageID，获取单条 message 详情。
      Parameters:
      sessionId - OpenCode 会话 ID；不得为空
      messageId - 会话消息 ID
      Returns:
      OpenCode SDK 返回的消息详情对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • runSessionCommand

      public PromptResult runSessionCommand(String sessionId, String command, String arguments, String agent, String model)
      POST /session/:id/command，向 session 发送 slash command。
      Parameters:
      sessionId - OpenCode 会话 ID；不得为空
      command - OpenCode 斜杠命令或 CLI 子命令
      arguments - 传递给斜杠命令的参数文本；为空时不附加参数
      agent - 执行请求的智能体名称；为空时使用服务端默认智能体
      model - 模型标识，通常采用 provider/model 格式；为空时使用默认模型
      Returns:
      OpenCode SDK 返回的Prompt 结果对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • listQuestions

      public List<QuestionRequest> listQuestions()
      GET /question，列出所有待回答的问题。
      Returns:
      OpenCode Server 返回的问题请求列表；无数据时为空列表
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • replyQuestion

      public boolean replyQuestion(String requestId, List<String> answers)
      POST /question/:id/reply，回复问题。
      Parameters:
      requestId - 待回复的问题或权限请求 ID
      answers - 按问题顺序提交的答案列表
      Returns:
      操作成功返回 true，否则返回 false
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • rejectQuestion

      public boolean rejectQuestion(String requestId)
      POST /question/:id/reject，拒绝回答问题。
      Parameters:
      requestId - 待回复的问题或权限请求 ID
      Returns:
      操作成功返回 true，否则返回 false
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • listPermissions

      public List<PermissionRequest> listPermissions()
      GET /permission，列出所有待审批权限请求。
      Returns:
      OpenCode Server 返回的权限请求列表；无数据时为空列表
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • replyPermission

      public boolean replyPermission(String requestId, String response, boolean remember)
      POST /permission/:id/reply，回复权限请求。
      Parameters:
      requestId - 待回复的问题或权限请求 ID
      response - 权限请求响应值，例如 allow 或 deny
      remember - 是否记住本次权限决定并应用于后续同类请求
      Returns:
      操作成功返回 true，否则返回 false
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • setAuth

      public boolean setAuth(String providerId, Object body)
      PUT /auth/:id，设置 provider 凭证。
      Parameters:
      providerId - 模型提供方 ID
      body - 提交给服务端的请求体
      Returns:
      操作成功返回 true，否则返回 false
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • setAuthAsync

      public CompletableFuture<Boolean> setAuthAsync(String providerId, Object body)
      异步设置 provider 凭证。
      Parameters:
      providerId - 模型提供方 ID
      body - 提交给服务端的请求体
      Returns:
      异步结果；失败时以异常方式完成

    • removeAuth

      public boolean removeAuth(String providerId)
      DELETE /auth/:id，清除 provider 凭证。
      Parameters:
      providerId - 模型提供方 ID
      Returns:
      操作成功返回 true，否则返回 false
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • disposeInstance

      public boolean disposeInstance()
      POST /instance/dispose，释放当前 instance。
      Returns:
      操作成功返回 true，否则返回 false
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • globalDispose

      public boolean globalDispose()
      POST /global/dispose，释放所有 instance。
      Returns:
      操作成功返回 true，否则返回 false
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • globalUpgrade

      public boolean globalUpgrade(String target)
      POST /global/upgrade，升级 opencode。target 为 null 时升级到最新。
      Parameters:
      target - 升级目标版本；为空时由 CLI 选择最新版本
      Returns:
      操作成功返回 true，否则返回 false
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • getOkHttpClient

      public okhttp3.OkHttpClient getOkHttpClient()
      暴露 OkHttpClient 供 SSE 客户端复用。
      Returns:
      OpenCode SDK 返回的OkHttp 客户端对象

    • getObjectMapper

      public com.fasterxml.jackson.databind.ObjectMapper getObjectMapper()
      暴露 ObjectMapper 供转换器复用。
      Returns:
      OpenCode SDK 返回的JSON 映射器对象

    • executeAsync

      protected <T> CompletableFuture<T> executeAsync(okhttp3.Request request, Class<T> type, HttpCallCancellation cancellation)
      使用 OkHttp enqueue 异步执行并反序列化对象。
      Type Parameters:
      T - 响应体反序列化后的目标类型
      Parameters:
      request - 请求对象；不得为 null
      type - 目标 Java 类型，用于反序列化响应体
      cancellation - 取消信号；为 null 时不可由外部取消
      Returns:
      异步结果；失败时以异常方式完成

    • awaitFuture

      protected <T> T awaitFuture(CompletableFuture<T> future)
      在同步兼容入口等待异步 HTTP 结果，并保留中断状态及 SDK 异常语义。
      Type Parameters:
      T - Future 正常完成时返回的值类型
      Parameters:
      future - 需要同步等待的异步结果；异常完成时转换为 SDK 异常
      Returns:
      OpenCode SDK 返回的反序列化后的响应对象
      Throws:
      OpenCodeHttpException - HTTP 请求失败或响应无法解析

    • close

      public void close()
      释放当前对象持有的连接、订阅或执行资源；重复调用是安全的。
      Specified by:
      close in interface AutoCloseable