opencode-acp-client 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +220 -2
  3. package/README.zh.md +199 -0
  4. package/dist/acp/capabilities.d.ts +168 -0
  5. package/dist/acp/capabilities.js +240 -0
  6. package/dist/acp/capabilities.js.map +1 -0
  7. package/dist/acp/client.d.ts +241 -0
  8. package/dist/acp/client.js +767 -0
  9. package/dist/acp/client.js.map +1 -0
  10. package/dist/acp/types.d.ts +228 -0
  11. package/dist/acp/types.js +23 -0
  12. package/dist/acp/types.js.map +1 -0
  13. package/dist/acp-replay.d.ts +60 -0
  14. package/dist/acp-replay.js +188 -0
  15. package/dist/acp-replay.js.map +1 -0
  16. package/dist/contract.d.ts +435 -0
  17. package/dist/contract.js +126 -0
  18. package/dist/contract.js.map +1 -0
  19. package/dist/daemons.d.ts +39 -0
  20. package/dist/daemons.js +112 -0
  21. package/dist/daemons.js.map +1 -0
  22. package/dist/index.d.ts +268 -0
  23. package/dist/index.js +1882 -0
  24. package/dist/index.js.map +1 -0
  25. package/dist/opencode-bin.d.ts +73 -0
  26. package/dist/opencode-bin.js +109 -0
  27. package/dist/opencode-bin.js.map +1 -0
  28. package/dist/project.d.ts +81 -0
  29. package/dist/project.js +230 -0
  30. package/dist/project.js.map +1 -0
  31. package/dist/server.d.ts +743 -0
  32. package/dist/server.js +5029 -0
  33. package/dist/server.js.map +1 -0
  34. package/dist/session-map.d.ts +89 -0
  35. package/dist/session-map.js +305 -0
  36. package/dist/session-map.js.map +1 -0
  37. package/dist/sessions-command.d.ts +70 -0
  38. package/dist/sessions-command.js +188 -0
  39. package/dist/sessions-command.js.map +1 -0
  40. package/dist/sse.d.ts +40 -0
  41. package/dist/sse.js +147 -0
  42. package/dist/sse.js.map +1 -0
  43. package/dist/state.d.ts +161 -0
  44. package/dist/state.js +135 -0
  45. package/dist/state.js.map +1 -0
  46. package/dist/subagent-sessions.d.ts +71 -0
  47. package/dist/subagent-sessions.js +107 -0
  48. package/dist/subagent-sessions.js.map +1 -0
  49. package/dist/translate/events.d.ts +231 -0
  50. package/dist/translate/events.js +1244 -0
  51. package/dist/translate/events.js.map +1 -0
  52. package/dist/upgrade.d.ts +56 -0
  53. package/dist/upgrade.js +162 -0
  54. package/dist/upgrade.js.map +1 -0
  55. package/package.json +66 -4
package/LICENSE ADDED
@@ -0,0 +1,202 @@
1
+
2
+ Apache License
3
+ Version 2.0, January 2004
4
+ http://www.apache.org/licenses/
5
+
6
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
+
8
+ 1. Definitions.
9
+
10
+ "License" shall mean the terms and conditions for use, reproduction,
11
+ and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by
14
+ the copyright owner that is granting the License.
15
+
16
+ "Legal Entity" shall mean the union of the acting entity and all
17
+ other entities that control, are controlled by, or are under common
18
+ control with that entity. For the purposes of this definition,
19
+ "control" means (i) the power, direct or indirect, to cause the
20
+ direction or management of such entity, whether by contract or
21
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
+ outstanding shares, or (iii) beneficial ownership of such entity.
23
+
24
+ "You" (or "Your") shall mean an individual or Legal Entity
25
+ exercising permissions granted by this License.
26
+
27
+ "Source" form shall mean the preferred form for making modifications,
28
+ including but not limited to software source code, documentation
29
+ source, and configuration files.
30
+
31
+ "Object" form shall mean any form resulting from mechanical
32
+ transformation or translation of a Source form, including but
33
+ not limited to compiled object code, generated documentation,
34
+ and conversions to other media types.
35
+
36
+ "Work" shall mean the work of authorship, whether in Source or
37
+ Object form, made available under the License, as indicated by a
38
+ copyright notice that is included in or attached to the work
39
+ (an example is provided in the Appendix below).
40
+
41
+ "Derivative Works" shall mean any work, whether in Source or Object
42
+ form, that is based on (or derived from) the Work and for which the
43
+ editorial revisions, annotations, elaborations, or other modifications
44
+ represent, as a whole, an original work of authorship. For the purposes
45
+ of this License, Derivative Works shall not include works that remain
46
+ separable from, or merely link (or bind by name) to the interfaces of,
47
+ the Work and Derivative Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright owner
53
+ or by an individual or Legal Entity authorized to submit on behalf of
54
+ the copyright owner. For the purposes of this definition, "submitted"
55
+ means any form of electronic, verbal, or written communication sent
56
+ to the Licensor or its representatives, including but not limited to
57
+ communication on electronic mailing lists, source code control systems,
58
+ and issue tracking systems that are managed by, or on behalf of, the
59
+ Licensor for the purpose of discussing and improving the Work, but
60
+ excluding communication that is conspicuously marked or otherwise
61
+ designated in writing by the copyright owner as "Not a Contribution."
62
+
63
+ "Contributor" shall mean Licensor and any individual or Legal Entity
64
+ on behalf of whom a Contribution has been received by Licensor and
65
+ subsequently incorporated within the Work.
66
+
67
+ 2. Grant of Copyright License. Subject to the terms and conditions of
68
+ this License, each Contributor hereby grants to You a perpetual,
69
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
+ copyright license to reproduce, prepare Derivative Works of,
71
+ publicly display, publicly perform, sublicense, and distribute the
72
+ Work and such Derivative Works in Source or Object form.
73
+
74
+ 3. Grant of Patent License. Subject to the terms and conditions of
75
+ this License, each Contributor hereby grants to You a perpetual,
76
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
+ (except as stated in this section) patent license to make, have made,
78
+ use, offer to sell, sell, import, and otherwise transfer the Work,
79
+ where such license applies only to those patent claims licensable
80
+ by such Contributor that are necessarily infringed by their
81
+ Contribution(s) alone or by combination of their Contribution(s)
82
+ with the Work to which such Contribution(s) was submitted. If You
83
+ institute patent litigation against any entity (including a
84
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+ or a Contribution incorporated within the Work constitutes direct
86
+ or contributory patent infringement, then any patent licenses
87
+ granted to You under this License for that Work shall terminate
88
+ as of the date such litigation is filed.
89
+
90
+ 4. Redistribution. You may reproduce and distribute copies of the
91
+ Work or Derivative Works thereof in any medium, with or without
92
+ modifications, and in Source or Object form, provided that You
93
+ meet the following conditions:
94
+
95
+ (a) You must give any other recipients of the Work or
96
+ Derivative Works a copy of this License; and
97
+
98
+ (b) You must cause any modified files to carry prominent notices
99
+ stating that You changed the files; and
100
+
101
+ (c) You must retain, in the Source form of any Derivative Works
102
+ that You distribute, all copyright, patent, trademark, and
103
+ attribution notices from the Source form of the Work,
104
+ excluding those notices that do not pertain to any part of
105
+ the Derivative Works; and
106
+
107
+ (d) If the Work includes a "NOTICE" text file as part of its
108
+ distribution, then any Derivative Works that You distribute must
109
+ include a readable copy of the attribution notices contained
110
+ within such NOTICE file, excluding those notices that do not
111
+ pertain to any part of the Derivative Works, in at least one
112
+ of the following places: within a NOTICE text file distributed
113
+ as part of the Derivative Works; within the Source form or
114
+ documentation, if provided along with the Derivative Works; or,
115
+ within a display generated by the Derivative Works, if and
116
+ wherever such third-party notices normally appear. The contents
117
+ of the NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own attribution
119
+ notices within Derivative Works that You distribute, alongside
120
+ or as an addendum to the NOTICE text from the Work, provided
121
+ that such additional attribution notices cannot be construed
122
+ as modifying the License.
123
+
124
+ You may add Your own copyright statement to Your modifications and
125
+ may provide additional or different license terms and conditions
126
+ for use, reproduction, or distribution of Your modifications, or
127
+ for any such Derivative Works as a whole, provided Your use,
128
+ reproduction, and distribution of the Work otherwise complies with
129
+ the conditions stated in this License.
130
+
131
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132
+ any Contribution intentionally submitted for inclusion in the Work
133
+ by You to the Licensor shall be under the terms and conditions of
134
+ this License, without any additional terms or conditions.
135
+ Notwithstanding the above, nothing herein shall supersede or modify
136
+ the terms of any separate license agreement you may have executed
137
+ with Licensor regarding such Contributions.
138
+
139
+ 6. Trademarks. This License does not grant permission to use the trade
140
+ names, trademarks, service marks, or product names of the Licensor,
141
+ except as required for reasonable and customary use in describing the
142
+ origin of the Work and reproducing the content of the NOTICE file.
143
+
144
+ 7. Disclaimer of Warranty. Unless required by applicable law or
145
+ agreed to in writing, Licensor provides the Work (and each
146
+ Contributor provides its Contributions) on an "AS IS" BASIS,
147
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+ implied, including, without limitation, any warranties or conditions
149
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+ PARTICULAR PURPOSE. You are solely responsible for determining the
151
+ appropriateness of using or redistributing the Work and assume any
152
+ risks associated with Your exercise of permissions under this License.
153
+
154
+ 8. Limitation of Liability. In no event and under no legal theory,
155
+ whether in tort (including negligence), contract, or otherwise,
156
+ unless required by applicable law (such as deliberate and grossly
157
+ negligent acts) or agreed to in writing, shall any Contributor be
158
+ liable to You for damages, including any direct, indirect, special,
159
+ incidental, or consequential damages of any character arising as a
160
+ result of this License or out of the use or inability to use the
161
+ Work (including but not limited to damages for loss of goodwill,
162
+ work stoppage, computer failure or malfunction, or any and all
163
+ other commercial damages or losses), even if such Contributor
164
+ has been advised of the possibility of such damages.
165
+
166
+ 9. Accepting Warranty or Additional Liability. While redistributing
167
+ the Work or Derivative Works thereof, You may choose to offer,
168
+ and charge a fee for, acceptance of support, warranty, indemnity,
169
+ or other liability obligations and/or rights consistent with this
170
+ License. However, in accepting such obligations, You may act only
171
+ on Your own behalf and on Your sole responsibility, not on behalf
172
+ of any other Contributor, and only if You agree to indemnify,
173
+ defend, and hold each Contributor harmless for any liability
174
+ incurred by, or claims asserted against, such Contributor by reason
175
+ of your accepting any such warranty or additional liability.
176
+
177
+ END OF TERMS AND CONDITIONS
178
+
179
+ APPENDIX: How to apply the Apache License to your work.
180
+
181
+ To apply the Apache License to your work, attach the following
182
+ boilerplate notice, with the fields enclosed by brackets "[]"
183
+ replaced with your own identifying information. (Don't include
184
+ the brackets!) The text should be enclosed in the appropriate
185
+ comment syntax for the file format. We also recommend that a
186
+ file or class name and description of purpose be included on the
187
+ same "printed page" as the copyright notice for easier
188
+ identification within third-party archives.
189
+
190
+ Copyright 2026 opencode-acp-client contributors
191
+
192
+ Licensed under the Apache License, Version 2.0 (the "License");
193
+ you may not use this file except in compliance with the License.
194
+ You may obtain a copy of the License at
195
+
196
+ http://www.apache.org/licenses/LICENSE-2.0
197
+
198
+ Unless required by applicable law or agreed to in writing, software
199
+ distributed under the License is distributed on an "AS IS" BASIS,
200
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201
+ See the License for the specific language governing permissions and
202
+ limitations under the License.
package/README.md CHANGED
@@ -1,3 +1,221 @@
1
- # Temporary Holding Version
1
+ # opencode-acp-client
2
2
 
3
- 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.
3
+ > 中文版:[README.zh.md](README.zh.md)
4
+
5
+ > **Not built by the OpenCode team and not affiliated with them in any way.** This is a
6
+ > community-maintained project. "opencode v2" here names the open-source opencode v2 TUI this
7
+ > project drives — you install and run it yourself as a separate program; this project neither
8
+ > bundles it nor speaks for it.
9
+
10
+ Use the **opencode v2 TUI** as the interface, driving **any ACP agent** (a terminal
11
+ **[ACP](https://agentclientprotocol.com) client**).
12
+
13
+ ```
14
+ opencode v2 TUI ──HTTP + SSE──▶ opencode-acp-client ──ACP stdio──▶ any ACP agent
15
+ (the interface)
16
+ (the ACP client)
17
+ dsh --profile acp /
18
+ opencode acp / qwen --acp /
19
+ claude-acp / codex-acp …
20
+ ```
21
+
22
+ **Who it is for**: people who like the opencode v2 TUI — who have learned its keybindings, its
23
+ command palette, its session tabs — and want to keep using that interface while driving an agent
24
+ that is **not** opencode's own.
25
+
26
+ ## Install
27
+
28
+ ### 1. Install opencode v2 first
29
+
30
+ This tool **does not ship the TUI**; it drives an **opencode v2** you install yourself
31
+ (`>=2.0.0`; the latest release is recommended). **Skip this step if you already have it** (confirm
32
+ with `opencode --version` — it must be v2.x); otherwise, any one of:
33
+
34
+ ```bash
35
+ curl -fsSL https://opencode.ai/v2/install | bash # the official install script
36
+ npm install -g @opencode/cli # or npm (the package is @opencode/cli)
37
+ ```
38
+
39
+ Check it: `opencode --version` must print **v2.x**. v1 will not do — it speaks a different event
40
+ vocabulary, and this tool refuses to start against it.
41
+
42
+ ### 2. Install this tool
43
+
44
+ Needs **Node ≥ 20**.
45
+
46
+ ```bash
47
+ # Option 1: from npm (recommended — you get a prebuilt package)
48
+ npm install -g opencode-acp-client
49
+
50
+ # Option 2: straight from source (point at the Git repository; npm fetches and builds it)
51
+ npm install -g git+https://github.com/pi-is314/opencode-acp-client.git
52
+ ```
53
+
54
+ Both give you exactly the same thing. Option 2 bypasses the npm registry — useful to track the
55
+ main branch, or when the registry is not an option — and it compiles once at install time with
56
+ `typescript` (a dozen seconds or so), so it needs registry access to fetch the compiler.
57
+
58
+ Two command names are installed, pointing at the same entry: **`opencode-acp-client`** (the
59
+ primary name) and **`oc-acp-client`** (a short alias).
60
+
61
+ When the TUI is not on `PATH`, point at it with `$OPENCODE_BIN`; the version is checked at
62
+ startup and reported rather than guessed.
63
+
64
+ ## Use
65
+
66
+ ```bash
67
+ npm install -g opencode-acp-client
68
+
69
+ oc-acp-client -- dsh --profile acp # dsh's built-in ACP profile
70
+ oc-acp-client -- qwen --acp # qwen-code
71
+ oc-acp-client -- opencode acp # our bridge turns `opencode acp` back into opencode's own http protocol :)
72
+ ```
73
+
74
+ The command after `--` is the agent; anything that speaks ACP over stdio works. One command
75
+ starts the TUI plus the adapter layer; quitting the TUI (or Ctrl-C) stops the agent too, leaving
76
+ no stray processes.
77
+
78
+ Beyond those, plenty of other agents implement ACP — for example
79
+ [gemini-cli](https://github.com/google-gemini/gemini-cli) (`gemini --acp`),
80
+ [Pi](https://github.com/badlogic/pi-mono) (through the [pi-acp](https://github.com/svkozak/pi-acp) adapter),
81
+ [GitHub Copilot](https://github.com/features/copilot),
82
+ [Kimi CLI](https://github.com/MoonshotAI/kimi-cli),
83
+ [Goose](https://block.github.io/goose/), [Cursor](https://cursor.com/docs/cli/acp),
84
+ [Kiro CLI](https://kiro.dev/docs/cli/acp/), [Cline](https://cline.bot/),
85
+ [OpenHands](https://docs.openhands.dev/openhands/usage/run-openhands/acp), and more.
86
+ **More ACP agents are listed here**: <https://agentclientprotocol.com/get-started/agents>.
87
+
88
+ **Resuming a session:**
89
+
90
+ ```bash
91
+ opencode-acp-client -c # the most recent one in this directory
92
+ opencode-acp-client -s ses_xxxxx # a specific session
93
+ ```
94
+
95
+ `-s` / `-c` do **not** accept an agent command — which agent to use comes from the session map,
96
+ and the CLI starts it for you. Where do ids come from? The `Continue` line printed when the TUI
97
+ exits has been rewritten into a command you can paste; alternatively:
98
+
99
+ ```bash
100
+ python3 scripts/list-sessions.py # the newest 20: id, age, title, directory
101
+ python3 scripts/list-sessions.py my-project # filter by title/directory/id substring
102
+ ```
103
+
104
+ **One client serves one agent.** That is by design, not a gap: the model/provider belong to the
105
+ agent, and mixing two agents' tabs into one TUI is exactly where "the new tab shows the other
106
+ agent's models" came from. So the TUI's tab layout is isolated per agent
107
+ (`~/.opencode-acp-client/opencode/<agent-slug>/`), and a session belonging to another agent is
108
+ refused (`404`). `--` is for a **new** session only.
109
+
110
+ ## Agents measured here
111
+
112
+ Every row is a real run, not copied from documentation.
113
+
114
+ | Agent | Command |
115
+ |---|---|
116
+ | dsh (built-in ACP profile) | `dsh --profile acp` |
117
+ | dsh + [deepseek-harness-acp](https://github.com/openma-ai/deepseek-harness-acp) (openma's plugin) | `dsh --profile <your profile>` |
118
+ | opencode | `opencode acp` |
119
+ | [qwen-code](https://github.com/QwenLM/qwen-code) | `qwen --acp` |
120
+ | [claude-acp](https://github.com/agentclientprotocol/claude-agent-acp) | `npx -y @agentclientprotocol/claude-agent-acp` |
121
+ | [codex-acp](https://github.com/agentclientprotocol/codex-acp) | `npx -y @agentclientprotocol/codex-acp` |
122
+
123
+ ## Common options
124
+
125
+ | Option | Meaning |
126
+ |---|---|
127
+ | `<directory>` | the working directory (opencode's spelling; `--directory` / `-C` also forward to the TUI) |
128
+ | `-s <id>` / `--session <id>` | resume that session |
129
+ | `-c` / `--continue` | resume the most recent session in this directory |
130
+ | `--no-tui` | serve the HTTP/SSE surface only, without the TUI |
131
+ | `--bridge-port <n>` | serve on this port only (implies `--no-tui`) |
132
+ | `--bridge-log <path>` | where the bridge log goes |
133
+ | `$OPENCODE_BIN` | the opencode v2 binary |
134
+
135
+ **These are the only options that reach the TUI** (with opencode v2's own semantics, not ours):
136
+
137
+ | Option | How it reaches the TUI |
138
+ |---|---|
139
+ | `--auto` | forwarded verbatim (auto-approve permissions that are not explicitly denied) |
140
+ | `--prompt <text>` | forwarded verbatim (prefill the composer) |
141
+ | `--print-logs` | forwarded verbatim |
142
+ | `--log-level <level>` | forwarded verbatim |
143
+ | `-c` / `--continue` | forwarded verbatim — the TUI reads its own remembered session list |
144
+ | `-s <id>` / `--session <id>` | **the bridge resolves it first**: it accepts the `ses_…` you were shown, then hands the TUI a `--session` |
145
+
146
+ `--server` / `--standalone` are ours (the bridge *is* that server) — they are dropped, **not**
147
+ forwarded. Nothing else goes to the TUI: subcommands like `auth`, `plugin` and `upgrade` pass
148
+ straight through to the opencode **binary** instead (see below).
149
+
150
+ `--help` prints opencode v2's own help first, then this tool's section.
151
+
152
+ **Subcommands**: `models` / `api` / `session` go through the bridge (the answer belongs to the
153
+ agent you attached); the rest (`auth`, `plugin`, `upgrade`, `debug`, …) pass straight through to
154
+ opencode. `ps` lists the bridge processes this tool has started.
155
+
156
+ ## Files it writes
157
+
158
+ All under `~/.opencode-acp-client/`. It **never writes into a native opencode v2 install**; the
159
+ session map stores ids, directories, titles and the agent's argv — **no message content and no
160
+ credentials**.
161
+
162
+ | Path | What it is |
163
+ |---|---|
164
+ | `sessions.json` | the session map (visible id ↔ the agent's own id, directory, title, agent) |
165
+ | `opencode/<agent-slug>/` | that agent's TUI state and data; config (`tui.json`, plugins, themes) is shared with your own install |
166
+ | `daemons/<pid>.json` | the registry `ps` uses; removed on a clean exit |
167
+
168
+ ## What a resumed session looks like
169
+
170
+ It depends on which capability the agent announces — the tab title tells you which case you are in:
171
+
172
+ - It has `loadSession` → history is replayed; you see the original conversation.
173
+ - Only `sessionCapabilities.resume` (dsh's built-in `acp` profile is like this) → ACP's
174
+ `session/resume` **does not replay history by spec**, so the tab is empty, but it keeps the
175
+ real name and carries a `◈ Notice` explaining why. **Whether the context survived is not
176
+ guaranteed by the spec.**
177
+ - Neither → the old session cannot be reattached; the tab becomes a **new conversation** titled
178
+ `[new conversation] <directory name>`.
179
+
180
+ ## Platforms and versions measured
181
+
182
+ The **whole gate** (typecheck, unit tests, the 52-probe OpenAPI check, and every real-TUI mode in
183
+ tmux) has run on **macOS** and on **Debian 12**: **v2.0.0, v2.1.0, v2.2.0, v2.3.0** on both,
184
+ plus intermediate releases such as v2.2.7 on macOS. Windows runs typecheck and the unit tests;
185
+ its TUI is not measured (no tmux). Sixteen releases are recorded one row each in
186
+ [docs/COMPAT-OPENCODE.md](docs/COMPAT-OPENCODE.md).
187
+
188
+ ## Design rules
189
+
190
+ 1. **Every inbound request gets an answer.** An agent that asks something and hears nothing back
191
+ waits forever; anything we do not support is refused explicitly so the agent can degrade.
192
+ 2. **Never assume a capability exists.** ACP is negotiated; the degradation rules are in
193
+ [docs/ACP-COMPAT.md](docs/ACP-COMPAT.md).
194
+ 3. **Prefer a noisy truth to a quiet guess.** A gap must be discoverable, not silently rendered
195
+ as nothing.
196
+
197
+ ## Known gaps
198
+
199
+ - Unimplemented routes: pty, MCP auth, provider OAuth, worktree changes, revert/share, most of
200
+ `/tui/*` — they answer with a well-formed empty envelope, or a logged 404. The 355 requests a
201
+ real session makes are all covered.
202
+ - **Other v2 clients are not recommended yet**: the state roots are injected into the TUI child
203
+ we spawn ourselves, and no other client can be given them, so its tabs are not isolated per
204
+ agent (see above).
205
+
206
+ ## Docs
207
+
208
+ - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — the process model and one turn end to end
209
+ - [docs/PROTOCOL.md](docs/PROTOCOL.md) — the opencode v2 surface we implement
210
+ - [docs/ACP-MATRIX.md](docs/ACP-MATRIX.md) — the ACP method matrix, event variants, deliberate deviations
211
+ - [docs/ACP-COMPAT.md](docs/ACP-COMPAT.md) — the runtime capability degradation rules
212
+ - [docs/COMPAT-OPENCODE.md](docs/COMPAT-OPENCODE.md) — version policy and the per-release record
213
+ - [docs/SESSION-LIFECYCLE.md](docs/SESSION-LIFECYCLE.md) — sessions, the map, the resume paths
214
+ - [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) — development notes and the traps
215
+ - [AGENTS.md](AGENTS.md) — the entry point for developing this repository
216
+
217
+ ## License
218
+
219
+ [Apache-2.0](LICENSE). This project launches the opencode v2 binary as a separate process and
220
+ talks to its published HTTP API; it **links no third-party source**, so the licence stands on its
221
+ own.
package/README.zh.md ADDED
@@ -0,0 +1,199 @@
1
+ # opencode-acp-client
2
+
3
+ > English: [README.md](README.md)
4
+
5
+ > **不是 OpenCode 团队构建的,也与他们没有任何关联。** 这是一个社区维护的项目。
6
+ > 这里说的 “opencode v2” 指本项目驱动的开源 opencode v2 TUI —— 它由你自己安装、作为独立程序运行,
7
+ > 本项目不打包它,也不代表官方背书。
8
+
9
+ 用 **opencode v2 的 TUI** 当界面,去驱动**任意 ACP agent**(一个终端
10
+ **[ACP](https://agentclientprotocol.com) 客户端**)。
11
+
12
+ ```
13
+ opencode v2 TUI ──HTTP + SSE──▶ opencode-acp-client ──ACP stdio──▶ 任意 ACP agent
14
+ (界面)
15
+ (ACP 客户端)
16
+ dsh --profile acp /
17
+ opencode acp / qwen --acp /
18
+ claude-acp / codex-acp …
19
+ ```
20
+
21
+ **适合谁用**:喜欢、习惯了 opencode v2 的 TUI 的人 —— 熟悉它的按键、命令面板、会话 tab ——
22
+ 希望继续用这套界面,同时驱动一个**不是 opencode 自己的** agent。
23
+
24
+ ## 安装
25
+
26
+ ### 第一步:先装 opencode v2
27
+
28
+ 本工具**不自带 TUI**,它驱动的是你自己装的 **opencode v2**(`>=2.0.0`,建议最新版)。
29
+ **已经装了就跳过这一步**(用 `opencode --version` 确认是 v2.x);没装则任选一种:
30
+
31
+ ```bash
32
+ curl -fsSL https://opencode.ai/v2/install | bash # 官方安装脚本
33
+ npm install -g @opencode/cli # 或者用 npm(包名是 @opencode/cli)
34
+ ```
35
+
36
+ 装完确认:`opencode --version` 应输出 **v2.x**(v1 不行 —— 它的事件词汇完全不同,本工具会拒绝启动)。
37
+
38
+ ### 第二步:装本工具
39
+
40
+ 需要 **Node ≥ 20**。
41
+
42
+ ```bash
43
+ # 方式一:从 npm 装(推荐,装的是构建好的包)
44
+ npm install -g opencode-acp-client
45
+
46
+ # 方式二:直接从源码装(指定 Git 仓库即可;npm 会拉代码并在本地构建好)
47
+ npm install -g git+https://github.com/pi-is314/opencode-acp-client.git
48
+ ```
49
+
50
+ 两种方式装出来的东西完全一样。方式二不经过 npm 源,适合想跟主干代码、或者 npm 装不上的情况;
51
+ 它会在安装时用 `typescript` 现场编译一次(约十几秒),所以需要能访问 npm 源去取编译器。
52
+
53
+ 装出两个命令名,指向同一入口:**`opencode-acp-client`**(主名)和 **`oc-acp-client`**(短 alias)。
54
+
55
+ TUI 不在 `PATH` 上时,用 `$OPENCODE_BIN` 指过去;启动时会检查版本并报出来,而不是猜。
56
+
57
+ ## 使用
58
+
59
+ ```bash
60
+ npm install -g opencode-acp-client
61
+
62
+ oc-acp-client -- dsh --profile acp # 用 dsh 的内置 ACP profile
63
+ oc-acp-client -- qwen --acp # 用 qwen-code
64
+ oc-acp-client -- opencode acp # 用我们的桥把 opencode acp 转成 opencode 自己的 http 协议 :)
65
+ ```
66
+
67
+ `--` 后面那条命令就是 agent,说 ACP、走 stdio 的东西都能用。一条命令起 TUI + 适配层;
68
+ 退出 TUI(或 Ctrl-C)会把 agent 一起停掉,不留残余进程。
69
+
70
+ 除上面几个,还能驱动很多实现了 ACP 的 agent,例如
71
+ [gemini-cli](https://github.com/google-gemini/gemini-cli)(`gemini --acp`)、
72
+ [Pi](https://github.com/badlogic/pi-mono)(经 [pi-acp](https://github.com/svkozak/pi-acp) 适配)、
73
+ [GitHub Copilot](https://github.com/features/copilot)、
74
+ [Kimi CLI](https://github.com/MoonshotAI/kimi-cli)、
75
+ [Goose](https://block.github.io/goose/)、[Cursor](https://cursor.com/docs/cli/acp)、
76
+ [Kiro CLI](https://kiro.dev/docs/cli/acp/)、[Cline](https://cline.bot/)、
77
+ [OpenHands](https://docs.openhands.dev/openhands/usage/run-openhands/acp) 等。
78
+ **更多 ACP agent 见这个列表**:<https://agentclientprotocol.com/get-started/agents>。
79
+
80
+ **恢复会话**:
81
+
82
+ ```bash
83
+ opencode-acp-client -c # 当前目录最近的一条
84
+ opencode-acp-client -s ses_xxxxx # 指定会话
85
+ ```
86
+
87
+ `-s` / `-c` **不接受** agent 命令 —— 用哪个 agent 由会话映射表决定,CLI 替你启动它。
88
+ id 从哪来?退出 TUI 时打印的 `Continue` 行已被改写成可直接复制的一条命令;也可以:
89
+
90
+ ```bash
91
+ python3 scripts/list-sessions.py # 最新 20 条:id、多久之前、标题、目录
92
+ python3 scripts/list-sessions.py my-project # 按标题/目录/id 子串过滤
93
+ ```
94
+
95
+ **一个 client 只服务一个 agent。** 这是设计而非缺失:模型/provider 属于 agent,把两个 agent 的
96
+ tab 混在一个 TUI 里,正是「新 tab 显示成另一个 agent 的模型」的来源。所以 TUI 的 tab 布局按
97
+ agent 隔离(`~/.opencode-acp-client/opencode/<agent-slug>/`),属于其它 agent 的会话会被拒绝
98
+ (`404`)。`--` 只用于**新建**会话。
99
+
100
+ ## 实测过的 agent
101
+
102
+ 每行都是一次真跑,不是抄文档。
103
+
104
+ | Agent | 命令 |
105
+ |---|---|
106
+ | dsh(内置 ACP profile) | `dsh --profile acp` |
107
+ | dsh + [deepseek-harness-acp](https://github.com/openma-ai/deepseek-harness-acp)(openma 的插件) | `dsh --profile <你的 profile>` |
108
+ | opencode | `opencode acp` |
109
+ | [qwen-code](https://github.com/QwenLM/qwen-code) | `qwen --acp` |
110
+ | [claude-acp](https://github.com/agentclientprotocol/claude-agent-acp) | `npx -y @agentclientprotocol/claude-agent-acp` |
111
+ | [codex-acp](https://github.com/agentclientprotocol/codex-acp) | `npx -y @agentclientprotocol/codex-acp` |
112
+
113
+ ## 常用参数
114
+
115
+ | 参数 | 含义 |
116
+ |---|---|
117
+ | `<directory>` | 工作目录(opencode 的拼写;`--directory` / `-C` 也透传给 TUI)|
118
+ | `-s <id>` / `--session <id>` | 恢复指定会话 |
119
+ | `-c` / `--continue` | 恢复当前目录最近的会话 |
120
+ | `--no-tui` | 只提供 HTTP/SSE 面,不起 TUI |
121
+ | `--bridge-port <n>` | 只在这个端口提供服务(隐含 `--no-tui`)|
122
+ | `--bridge-log <path>` | 桥日志位置 |
123
+ | `$OPENCODE_BIN` | opencode v2 二进制路径 |
124
+
125
+ **能到 TUI 的参数就这么几个**(语义是 opencode v2 的,不是我们的):
126
+
127
+ | 参数 | 怎么到 TUI |
128
+ |---|---|
129
+ | `--auto` | 原样转发(自动批准未被显式拒绝的权限)|
130
+ | `--prompt <text>` | 原样转发(起 TUI 前先填好这句)|
131
+ | `--print-logs` | 原样转发 |
132
+ | `--log-level <level>` | 原样转发 |
133
+ | `-c` / `--continue` | 原样转发 —— 由 TUI 自己去读它记的会话列表 |
134
+ | `-s <id>` / `--session <id>` | **桥先解析**:认你看到的 `ses_…`,再以 `--session` 交给 TUI |
135
+
136
+ `--server` / `--standalone` 由本工具接管(桥就是那个 server),传了会被丢掉而**不是**转发。
137
+ 其余参数不转给 TUI:`auth`、`plugin`、`upgrade` 这类子命令是**原样直通给 opencode 可执行文件本身**(见下)。
138
+
139
+ `--help` 先打印 opencode v2 自己的帮助,再追加本工具的参数段。
140
+
141
+ **子命令**:`models` / `api` / `session` 走桥(答案属于你接的 agent),其余(`auth`、`plugin`、
142
+ `upgrade`、`debug`…)原样直通给 opencode。`ps` 列出本工具启动过的桥进程。
143
+
144
+ ## 它写了哪些文件
145
+
146
+ 都在 `~/.opencode-acp-client/` 下。**不写原生 opencode v2 的安装目录**;会话映射表只存
147
+ id、目录、标题和创建它的 agent argv —— **不存消息内容,也不存凭证**。
148
+
149
+ | 路径 | 是什么 |
150
+ |---|---|
151
+ | `sessions.json` | 会话映射表(可见 id ↔ agent 自己的 id、目录、标题、agent)|
152
+ | `opencode/<agent-slug>/` | 该 agent 的 TUI 状态与数据;配置(`tui.json`、插件、主题)与你自己的安装共享 |
153
+ | `daemons/<pid>.json` | `ps` 用的注册表,正常退出即删 |
154
+
155
+ ## 恢复出来是什么样
156
+
157
+ 取决于 agent 宣告了哪个能力 —— tab 标题会告诉你是哪一种:
158
+
159
+ - 有 `loadSession` → 回放历史,看得到原来的对话。
160
+ - 只有 `sessionCapabilities.resume`(dsh 官方 `acp` profile 就是这样)→ ACP 的
161
+ `session/resume` **按规范不重放历史**,tab 是空的,但保留真名,并有一条 `◈ Notice`
162
+ 说明原因。**上下文是否还在,规范不保证。**
163
+ - 两个都没有 → 旧会话接不回来;tab 变成一个**新对话**,标题 `[new conversation] <目录名>`。
164
+
165
+ ## 已实测的平台与版本
166
+
167
+ **完整门控**(typecheck、单测、52 探针的 OpenAPI 校验、tmux 里的全部真 TUI 模式)在
168
+ **macOS** 与 **Debian 12** 上各跑过:两边都是 **v2.0.0、v2.1.0、v2.2.0、v2.3.0**,
169
+ macOS 上另有 v2.2.7 等中间版本。Windows 上跑 typecheck 与单测,TUI 未实测(没有 tmux)。
170
+ 16 个 release 逐个记录在 [docs/COMPAT-OPENCODE.zh.md](docs/COMPAT-OPENCODE.zh.md)。
171
+
172
+ ## 设计准则
173
+
174
+ 1. **每个入站请求都要回答。** agent 问了什么却听不到回音,会永远等下去;不支持的也要明确拒绝,让它能降级。
175
+ 2. **永不假设能力存在。** ACP 是协商出来的,降级规则见 [docs/ACP-COMPAT.zh.md](docs/ACP-COMPAT.zh.md)。
176
+ 3. **宁可吵闹的真相,不要安静的猜测。** 缺口要能被发现,而不是静默地什么都不渲染。
177
+
178
+ ## 已知缺口
179
+
180
+ - 未实现的路由:pty、MCP auth、provider OAuth、worktree 变更、revert/share、大部分 `/tui/*` ——
181
+ 它们返回格式正确的空信封,或一条记了日志的 404。真实会话用到的 355 个请求已全覆盖。
182
+ - **其它 v2 客户端暂不推荐**:状态根是注入给我们自己拉起的 TUI 子进程的,别的客户端拿不到,
183
+ 它的 tab 不按 agent 隔离(见上)。
184
+
185
+ ## 文档
186
+
187
+ - [docs/ARCHITECTURE.zh.md](docs/ARCHITECTURE.zh.md) —— 进程模型与一个回合的时序
188
+ - [docs/PROTOCOL.zh.md](docs/PROTOCOL.zh.md) —— 我们实现的 opencode v2 接口面
189
+ - [docs/ACP-MATRIX.zh.md](docs/ACP-MATRIX.zh.md) —— ACP 方法矩阵、事件变体、故意偏离
190
+ - [docs/ACP-COMPAT.zh.md](docs/ACP-COMPAT.zh.md) —— 运行时能力降级规则
191
+ - [docs/COMPAT-OPENCODE.zh.md](docs/COMPAT-OPENCODE.zh.md) —— 版本策略与逐版本实测记录
192
+ - [docs/SESSION-LIFECYCLE.zh.md](docs/SESSION-LIFECYCLE.zh.md) —— 会话、映射表、恢复链路
193
+ - [docs/DEVELOPMENT.zh.md](docs/DEVELOPMENT.zh.md) —— 开发笔记与坑
194
+ - [AGENTS.zh.md](AGENTS.zh.md) —— 开发本仓的入口
195
+
196
+ ## 许可证
197
+
198
+ [Apache-2.0](LICENSE)。本项目把 opencode v2 二进制作为独立进程启动、走它公开的 HTTP 接口面,
199
+ **不链接任何第三方源码**,所以许可独立成立。