dsh-opencode-acp 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-opencode-acp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# dsh-opencode-acp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/dsh-opencode-acp.svg)](https://www.npmjs.com/package/dsh-opencode-acp)
+[![licence: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)
+[![topic: dsh-plugin](https://img.shields.io/badge/topic-dsh--plugin-8250df.svg)](https://github.com/topics/dsh-plugin)
+
+Run [opencode](https://opencode.ai) as an ACP subagent inside DeepSeek Harness (DSH).
+
+Your main agent keeps its own model and context; `subagent_opencode` hands a self-contained task to
+opencode in a separate process, opencode does the work with **its own models, tools and free tier**,
+and only the final answer comes back. A settings page lets you switch models, choose the permission
+policy and working directory, and watch every run — including the opencode session id, duration and
+token usage.
+
+[中文说明](README.zh.md)
+
+## Why
+
+- **Two harnesses, one conversation.** DSH stays the driver. opencode brings its own free models and
+  its own tooling; nothing it does lands in your context or your token bill.
+- **You can see what happened.** Because this plugin speaks ACP itself, each run records the remote
+  session id, the model, the duration, tool-call count and token usage — so "which opencode session
+  was that?" has an answer.
+- **Settings without restarts.** Settings are read at the start of every delegation, so a saved
+  change applies to the next run.
+
+## Requirements
+
+| | |
+|---|---|
+| DeepSeek Harness | `>=0.2.1-rc.1 <0.3.0` (declared as `engines.dsh`; install refuses other versions) |
+| opencode | v2 with the `acp` subcommand (`opencode --version`, `opencode acp --help`) |
+| opencode auth | already logged in (`opencode auth login`); the child reuses your login and free models |
+
+## Install
+
+From the DSH Plugins page, or from a terminal:
+
+```sh
+# from npm (prebuilt, no build step)
+dsh plugin --profile default add dsh-opencode-acp
+
+# or from a tarball
+dsh plugin --profile default add ./dsh-opencode-acp-0.1.1.tgz
+```
+
+Then restart or refresh DSH. Two things appear:
+
+- a **delegation tool** named `subagent_opencode` for every agent in the profile;
+- **Settings → OpenCode 委派**, the configuration page.
+
+## Use
+
+Just ask for it, or call the tool directly:
+
+```
+Delegate to subagent_opencode: in this repo, add a unit test for parseDuration and report what you changed.
+```
+
+The call returns immediately with a child id; the completion notice carries opencode's final answer.
+The child gets only your task text and the working directory — never your conversation.
+
+## Settings
+
+| Group | Setting | Meaning |
+|---|---|---|
+| Model | main model | Picker built from the models your opencode has used, plus a free-form id |
+| Model | small model | opencode's model for titles and small jobs (blank = let opencode choose) |
+| Model | health check | Runs `opencode --version` and reports whether the executable resolves |
+| Execution | permission | `allow` auto-answers permission requests, `reject` denies them |
+| Execution | working directory | Follow the calling session, or pin one path |
+| Advanced | command / args | The opencode executable plus the `acp` argument |
+| Advanced | grace | Process teardown window in milliseconds |
+| Advanced | env | Extra environment variables as a JSON object |
+
+Settings live in `$DSH_HOME/opencode-acp/settings.json`; runs in `runs.json` beside it (last 100).
+
+## How it works
+
+```
+DSH agent ── subagent_opencode ──► ctx.subagents ──► dsh-opencode-acp (provider "opencode")
+                                                        │ spawn: opencode acp
+                                                        ▼
+                                              ACP over stdio (NDJSON JSON-RPC)
+                                       initialize → session/new → session/prompt
+                                                        │
+                                     ◄── agent_message_chunk, usage_update
+```
+
+- The ACP protocol carries no model parameter, so the model is decided on the opencode side. This
+  plugin injects `OPENCODE_CONFIG_CONTENT` into the child; `OPENCODE_CONFIG` (a file path) is
+  ignored by `opencode acp` in v2 — verified, not assumed.
+- Runs are one-shot: an external ACP child cannot receive follow-up messages, so it is not
+  continuable. For multi-turn delegation use DSH's built-in `subagent` instead.
+- The child process runs with your user account and is **not** confined by the DSH sandbox, exactly
+  like DSH's own `@deepseek-ai/dsh-subagent-acp`. Treat delegation as "opencode may do what you
+  could do".
+
+## Limits
+
+- Only assistant text is returned; opencode's tool traffic, reasoning and plans stay in its own
+  session.
+- A fresh process per run: expect a few seconds of startup on every delegation.
+- Windows, macOS and Linux are all supported. The default command is the npm-global opencode on
+  Windows (`%APPDATA%\npm\node_modules\@opencode\cli\bin\opencode.exe`) and `opencode` on `PATH`
+  elsewhere; override **Advanced → command** if your install differs.
+
+## Uninstall
+
+```sh
+dsh plugin --profile default remove dsh-opencode-acp
+```
+
+Removing the bundle removes the tool and the settings page; `$DSH_HOME/opencode-acp` stays until you
+delete it.
+
+## Development
+
+Plain JavaScript, no build step.
+
+```sh
+node --check index.js
+node --check client.js
+npm pack --dry-run
+```
+
+The Host half is `index.js` (ACP client, provider, storage, HTTP routes under `/.dsh-opencode-acp`),
+the browser half is `client.js` (a `settings.section` page registered through the client module
+table). Both are named exports; `cordis.patch.yml` inserts the two rows.
+
+## Licence
+
+MIT

package/README.zh.md

@@ -0,0 +1,121 @@
+# dsh-opencode-acp
+
+把 [opencode](https://opencode.ai) 接成 DeepSeek Harness（DSH）的子代理。
+
+主代理继续用自己的模型和上下文；`subagent_opencode` 把一件独立的任务交给另一个进程里的
+opencode，由它用**自己的模型、工具和免费额度**干活，只把最终答案带回来。设置页里可以切换模型、
+选择权限策略和工作目录，并查看每一次运行——包括 opencode 那边的会话 id、耗时和 token 用量。
+
+[English](README.md)
+
+## 为什么值得装
+
+- **两个 harness，一次对话。** DSH 负责调度，opencode 出模型和手脚；它干活的中间过程不进你的
+  上下文，也不进你的账单。
+- **看得见发生了什么。** 这个插件自己说 ACP，所以每次运行都会记下远端会话 id、模型、耗时、
+  工具调用次数和 token——"刚才那次是 opencode 里的哪个会话"有答案。
+- **改设置不用重启。** 设置在每次委派开始时读取，保存后下一次委派就生效。
+
+## 前置条件
+
+| | |
+|---|---|
+| DeepSeek Harness | `>=0.2.1-rc.1 <0.3.0`（写在 `engines.dsh` 里，不匹配会拒绝安装） |
+| opencode | v2，带 `acp` 子命令（`opencode --version`、`opencode acp --help` 能跑） |
+| opencode 登录 | 已登录（`opencode auth login`）；子进程复用它，包括免费模型 |
+
+## 安装
+
+在 DSH 的插件页面安装，或者用命令行：
+
+```sh
+# 从 npm（预构建，无需构建步骤）
+dsh plugin --profile default add dsh-opencode-acp
+
+# 或者从 tarball
+dsh plugin --profile default add ./dsh-opencode-acp-0.1.1.tgz
+```
+
+装完重启或刷新 DSH，会出现两样东西：
+
+- 一个叫 `subagent_opencode` 的**委派工具**，该 profile 下所有 agent 都能用；
+- **设置 → OpenCode 委派** 配置页。
+
+## 怎么用
+
+直接说，或者调工具：
+
+```
+交给 subagent_opencode：在这个仓库里给 parseDuration 补一个单元测试，并说明你改了什么。
+```
+
+调用立刻返回一个子代理 id，完成通知里带 opencode 的最终答复。子进程只拿到你的任务文本和工作
+目录，拿不到你的对话历史。
+
+## 设置项
+
+| 分组 | 设置 | 含义 |
+|---|---|---|
+| 模型 | 主模型 | 下拉列出你 opencode 用过的模型，也允许手填 id |
+| 模型 | 小模型 | opencode 生成标题/小任务用的模型（留空让它自己挑） |
+| 模型 | 健康检查 | 跑一次 `opencode --version`，确认可执行文件找得到 |
+| 执行 | 权限应答 | `allow` 自动放行权限请求，`reject` 一律拒绝 |
+| 执行 | 工作目录 | 跟随调用方会话，或固定一个路径 |
+| 高级 | 命令 / 参数 | opencode 可执行文件 + `acp` 参数 |
+| 高级 | 收尾宽限 | 子进程退出等待，毫秒 |
+| 高级 | 环境变量 | 额外环境变量（JSON 对象） |
+
+设置存在 `$DSH_HOME/opencode-acp/settings.json`，运行记录在同目录的 `runs.json`（最近 100 条）。
+
+## 原理
+
+```
+DSH agent ── subagent_opencode ──► ctx.subagents ──► dsh-opencode-acp（provider 名 "opencode"）
+                                                        │ spawn: opencode acp
+                                                        ▼
+                                              ACP over stdio（NDJSON JSON-RPC）
+                                       initialize → session/new → session/prompt
+                                                        │
+                                     ◄── agent_message_chunk、usage_update
+```
+
+- ACP 协议不带模型参数，所以模型只能在 opencode 侧决定。这个插件向子进程注入
+  `OPENCODE_CONFIG_CONTENT`；`OPENCODE_CONFIG`（文件路径）在 v2 的 `acp` 模式下会被忽略——这是
+  实测结论，不是猜的。
+- 一次性执行：外部 ACP 子代理收不到后续消息，所以不可追问。需要多轮请用 DSH 自带的 `subagent`。
+- 子进程用你的用户账号运行，**不受 DSH 沙箱约束**，和 DSH 官方的
+  `@deepseek-ai/dsh-subagent-acp` 行为一致。把它当成"opencode 能干你本人能干的事"。
+
+## 已知限制
+
+- 只回传 assistant 文本；opencode 的工具调用、思考、计划都留在它自己的会话里。
+- 每次运行新起一个进程，有数秒启动开销。
+- Windows / macOS / Linux 都支持。默认命令在 Windows 上是 npm 全局安装的
+  `%APPDATA%\npm\node_modules\@opencode\cli\bin\opencode.exe`，其他平台是 `PATH` 里的
+  `opencode`；装法不同就在 **高级 → 启动命令** 改掉。
+
+## 卸载
+
+```sh
+dsh plugin --profile default remove dsh-opencode-acp
+```
+
+移除后工具和设置页一起消失；`$DSH_HOME/opencode-acp` 里的数据要手动删。
+
+## 开发
+
+纯 JavaScript，没有构建步骤。
+
+```sh
+node --check index.js
+node --check client.js
+npm pack --dry-run
+```
+
+宿主半是 `index.js`（ACP 客户端、provider、存储、`/.dsh-opencode-acp` 下的 HTTP 路由），
+浏览器半是 `client.js`（通过客户端模块表注册的 `settings.section` 页面）。两半都是具名导出，
+`cordis.patch.yml` 插入两行。
+
+## 许可
+
+MIT