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.
- package/LICENSE +202 -0
- package/README.md +220 -2
- package/README.zh.md +199 -0
- package/dist/acp/capabilities.d.ts +168 -0
- package/dist/acp/capabilities.js +240 -0
- package/dist/acp/capabilities.js.map +1 -0
- package/dist/acp/client.d.ts +241 -0
- package/dist/acp/client.js +767 -0
- package/dist/acp/client.js.map +1 -0
- package/dist/acp/types.d.ts +228 -0
- package/dist/acp/types.js +23 -0
- package/dist/acp/types.js.map +1 -0
- package/dist/acp-replay.d.ts +60 -0
- package/dist/acp-replay.js +188 -0
- package/dist/acp-replay.js.map +1 -0
- package/dist/contract.d.ts +435 -0
- package/dist/contract.js +126 -0
- package/dist/contract.js.map +1 -0
- package/dist/daemons.d.ts +39 -0
- package/dist/daemons.js +112 -0
- package/dist/daemons.js.map +1 -0
- package/dist/index.d.ts +268 -0
- package/dist/index.js +1882 -0
- package/dist/index.js.map +1 -0
- package/dist/opencode-bin.d.ts +73 -0
- package/dist/opencode-bin.js +109 -0
- package/dist/opencode-bin.js.map +1 -0
- package/dist/project.d.ts +81 -0
- package/dist/project.js +230 -0
- package/dist/project.js.map +1 -0
- package/dist/server.d.ts +743 -0
- package/dist/server.js +5029 -0
- package/dist/server.js.map +1 -0
- package/dist/session-map.d.ts +89 -0
- package/dist/session-map.js +305 -0
- package/dist/session-map.js.map +1 -0
- package/dist/sessions-command.d.ts +70 -0
- package/dist/sessions-command.js +188 -0
- package/dist/sessions-command.js.map +1 -0
- package/dist/sse.d.ts +40 -0
- package/dist/sse.js +147 -0
- package/dist/sse.js.map +1 -0
- package/dist/state.d.ts +161 -0
- package/dist/state.js +135 -0
- package/dist/state.js.map +1 -0
- package/dist/subagent-sessions.d.ts +71 -0
- package/dist/subagent-sessions.js +107 -0
- package/dist/subagent-sessions.js.map +1 -0
- package/dist/translate/events.d.ts +231 -0
- package/dist/translate/events.js +1244 -0
- package/dist/translate/events.js.map +1 -0
- package/dist/upgrade.d.ts +56 -0
- package/dist/upgrade.js +162 -0
- package/dist/upgrade.js.map +1 -0
- 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
|
-
#
|
|
1
|
+
# opencode-acp-client
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+
**不链接任何第三方源码**,所以许可独立成立。
|