zcode-acp-server 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is derived from (or based upon) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 ZCode ACP Server Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,167 @@
+# zcode-acp-server
+
+[![CI](https://github.com/zcode-org/zcode-acp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/zcode-org/zcode-acp-server/actions/workflows/ci.yml)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+
+English | **[简体中文](README.zh-CN.md)**
+
+A standalone [Agent Client Protocol](https://agentclientprotocol.com/) (ACP) server that bridges the headless **ZCode** app-server to ACP-compatible editors such as [Zed](https://zed.dev) and JetBrains IDEs.
+
+The server launches the ZCode headless app-server (`zcode app-server --stdio`) as a subprocess, translates its internal event stream into ACP `session/update` notifications, and bridges ZCode's interaction channel to ACP — preferring `elicitation/create` when the client supports it, and falling back to `session/request_permission` otherwise — so an editor gets a first-class, native coding-agent experience.
+
+## Status
+
+Early in-development. Core scaffolding is in place; features are landing incrementally. See the project board for progress.
+
+## Requirements
+
+- **Node.js ≥ 22** (the bridge uses `node:sqlite` for tasks-index sync; the
+  ZCode CLI runtime also requires Node ≥ 22)
+- The `zcode` CLI installed and on `PATH` (or pointed at via `ZCODE_BIN`)
+- ZCode credentials at `~/.zcode/v2/config.json` (created by the ZCode app)
+
+## Install
+
+```bash
+git clone <repo-url>
+cd zcode-acp-server
+pnpm install
+pnpm build
+```
+
+The compiled entry point is `dist/index.js` (also exposed as the
+`zcode-acp-server` bin). Configure your ACP client to launch it — see
+**Configure Zed** below or your editor's ACP docs.
+
+## Configure Zed
+
+Add the server to Zed as a custom agent server. In `~/.config/zed/settings.json`
+(`%APPDATA%\Zed\settings.json` on Windows):
+
+```jsonc
+{
+  "agent_servers": {
+    "ZCode": {
+      "type": "custom",
+      "command": "node",
+      "args": ["/absolute/path/to/zcode-acp-server/dist/index.js"],
+      "env": {
+        // Point at the ZCode CLI bundled inside the desktop app (not on PATH by default).
+        // See the platform-specific path below.
+        "ZCODE_BIN": "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs",
+      },
+    },
+  },
+}
+```
+
+Restart Zed and pick **ZCode** from the agent dropdown.
+
+### `ZCODE_BIN` per platform
+
+The ZCode CLI ships inside the desktop app and is not added to `PATH`
+automatically. Point `ZCODE_BIN` at the bundled `zcode.cjs`:
+
+| Platform    | `ZCODE_BIN` path                                                            |
+| ----------- | --------------------------------------------------------------------------- |
+| **macOS**   | `/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs`                  |
+| **Windows** | `%LOCALAPPDATA%\Programs\ZCode\resources\glm\zcode.cjs`                     |
+| **Linux**   | Inside the extracted app directory: `<install-dir>/resources/glm/zcode.cjs` |
+
+> If the path doesn't match your install, locate it with:
+>
+> ```bash
+> # macOS / Linux
+> find / -name zcode.cjs -path '*resources/glm*' 2>/dev/null
+> # Windows (PowerShell)
+> Get-ChildItem -Path $env:LOCALAPPDATA,$env:APPDATA,'C:\Program Files' -Recurse -Filter zcode.cjs -ErrorAction SilentlyContinue
+> ```
+
+## Environment variables
+
+| Variable          | Default         | Purpose                                                                                                                                                                                                                                                                                                      |
+| ----------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ZCODE_BIN`       | `zcode`         | Path to the ZCode CLI binary or its `.cjs` entry                                                                                                                                                                                                                                                             |
+| `ZCODE_NODE`      | _(discovered)_  | Explicit Node binary to run `ZCODE_BIN` with (must support `node:sqlite`)                                                                                                                                                                                                                                    |
+| `ZCODE_MODEL`     | _(from config)_ | Override the active model id                                                                                                                                                                                                                                                                                 |
+| `ZCODE_BASE_URL`  | _(from config)_ | Override the provider base URL                                                                                                                                                                                                                                                                               |
+| `ZCODE_ACP_DEBUG` | _(unset)_       | Set to `1` to enable verbose diagnostic logs (event flow, probe loops, status updates). Default is quiet — only warnings (backend pipe errors, command/permission failures, lock timeouts) are emitted. Enable this when diagnosing bridge issues; the logs appear in `Zed.log` prefixed with `[zcode-acp]`. |
+
+## ACP Registry
+
+This server is compatible with the [ACP Registry](https://agentclientprotocol.com/get-started/registry). It advertises a single `agent`-type auth method at `initialize` time — the GLM API key is read from `~/.zcode/v2/config.json` by the ZCode backend, so **no editor-side credentials are required**.
+
+The registry submission assets live under [`registry/zcode-acp-server/`](registry/zcode-acp-server/) (`agent.json` + `icon.svg`). Once the package is published to npm, copy that directory into a fork of [`agentclientprotocol/registry`](https://github.com/agentclientprotocol/registry) and open a PR — the CI validates the `agent.json` schema, icon, and that `initialize` returns a non-empty `authMethods`.
+
+## Develop
+
+```bash
+pnpm install
+pnpm build       # tsc → dist/
+pnpm typecheck   # tsc --noEmit
+pnpm lint        # eslint (warnings advisory; errors fail CI)
+pnpm test        # vitest
+pnpm format      # prettier on src/
+```
+
+CI runs `typecheck`, `lint`, `build`, and `test` on every push and pull
+request — run them locally before pushing (see [CONTRIBUTING.md](CONTRIBUTING.md)).
+
+> **Tip (Node version)**: this repo pins Node 22 via a root `.node-version`
+> file. Pair it with [fnm](https://github.com/Schniz/fnm) or
+> [nvm](https://github.com/nvm-sh/nvm) to auto-switch on `cd`. pnpm itself is
+> managed by your local environment (corepack).
+
+## Architecture
+
+The server is organised in layers that mirror the ACP protocol:
+
+- `backend/` — ZCode subprocess client: spawn, reader-loop multiplexer, event-stream listener, sync request/response
+- `translators/` — turn ZCode events into ACP `session/update` notifications (event streaming + snapshot diff)
+- `interaction/` — bridge ZCode `interaction/*` server requests to ACP, preferring `elicitation/create` and falling back to `session/request_permission` (tool auth, ExitPlanMode, AskUserQuestion)
+- `handlers/` — ACP method handlers (`session/new`, `session/prompt`, ...) and the turn engine
+- `config/` — model / mode / thought-level configOptions and runtime model switching
+- `server.ts` — shared state and handler registration
+- `index.ts` — stdio wiring via the ACP SDK
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full architecture documentation.
+
+## Version Compatibility
+
+| ZCode CLI version |   Support    | Notes                                    |
+| :---------------: | :----------: | ---------------------------------------- |
+|   **>= 0.15.0**   |     Full     | All extension methods available          |
+|   **>= 0.14.8**   |     Full     | Event-stream push, all extension methods |
+|   **< 0.14.8**    | Incompatible | Event-stream subscription unavailable    |
+
+## Documentation
+
+- [Architecture](docs/ARCHITECTURE.md) — event stream, dual-path deduplication, module responsibilities
+- [Protocol](docs/PROTOCOL.md) — ZCode JSON-RPC protocol details
+- [Development](docs/DEVELOPMENT.md) — local development, debugging, adding extension methods
+- [Troubleshooting](docs/TROUBLESHOOTING.md) — common-issue troubleshooting
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for setup,
+code style, commit conventions, and the PR checklist. Notable changes are
+recorded in [CHANGELOG.md](CHANGELOG.md).
+
+## Related Projects
+
+- [zcode-open-bridge](https://github.com/tizerluo/zcode-open-bridge) — a community Python implementation that bridges ZCode to the MCP/ACP ecosystem. The design of this server references its bridge architecture and several handling strategies.
+
+## Acknowledgements
+
+- [Agent Client Protocol](https://agentclientprotocol.com/) (Apache-2.0) — the ACP specification
+- [ZCode](https://zcode.z.ai) / [Zhipu Z.AI](https://z.ai) — the GLM model and ZCode CLI
+- [zcode-open-bridge](https://github.com/tizerluo/zcode-open-bridge) — reference implementation that informed this server's design
+
+## License
+
+Apache-2.0. This project follows the same license as the upstream ACP specification.
+
+## Disclaimer
+
+This is an independent community project and is not affiliated with, endorsed
+by, or sponsored by Zhipu Z.AI. ZCode is a product of Zhipu Z.AI.

package/README.zh-CN.md

@@ -0,0 +1,163 @@
+# zcode-acp-server
+
+[![CI](https://github.com/zcode-org/zcode-acp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/zcode-org/zcode-acp-server/actions/workflows/ci.yml)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+
+**[English](README.md)** | 简体中文
+
+一个独立的 [Agent Client Protocol](https://agentclientprotocol.com/)（ACP）服务端，将无头模式的 **ZCode** app-server 桥接到支持 ACP 的编辑器，例如 [Zed](https://zed.dev) 和 JetBrains IDE。
+
+本服务端以子进程方式启动 ZCode 无头 app-server（`zcode app-server --stdio`），将其内部事件流翻译为 ACP `session/update` 通知，并把 ZCode 的交互通道桥接到 ACP —— 当客户端支持时优先使用 `elicitation/create`，否则回退到 `session/request_permission` —— 从而让编辑器获得原生的、一流的编码助手体验。
+
+## 状态
+
+早期开发中。核心框架已就绪，功能正在陆续加入。进度请看项目看板。
+
+## 环境要求
+
+- **Node.js ≥ 22**（桥接层用 `node:sqlite` 同步 tasks-index；ZCode CLI
+  运行时也要求 Node ≥ 22）
+- 已安装 `zcode` CLI 并位于 `PATH` 上（或通过 `ZCODE_BIN` 指定）
+- ZCode 凭证位于 `~/.zcode/v2/config.json`（由 ZCode App 创建）
+
+## 安装
+
+```bash
+git clone <repo-url>
+cd zcode-acp-server
+pnpm install
+pnpm build
+```
+
+编译产物入口为 `dist/index.js`（同时作为 `zcode-acp-server` bin 暴露）。在你的
+ACP 客户端里配置启动它 —— 见下方的 **在 Zed 中配置** 或你的编辑器的 ACP 文档。
+
+## 在 Zed 中配置
+
+将本服务端作为自定义 agent server 添加到 Zed。在 `~/.config/zed/settings.json`
+（Windows 上为 `%APPDATA%\Zed\settings.json`）中：
+
+```jsonc
+{
+  "agent_servers": {
+    "ZCode": {
+      "type": "custom",
+      "command": "node",
+      "args": ["/absolute/path/to/zcode-acp-server/dist/index.js"],
+      "env": {
+        // 指向桌面应用内置的 ZCode CLI（默认不在 PATH 上）。
+        // 各平台路径见下方表格。
+        "ZCODE_BIN": "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs",
+      },
+    },
+  },
+}
+```
+
+重启 Zed，然后从 agent 下拉菜单中选择 **ZCode**。
+
+### 各平台的 `ZCODE_BIN` 路径
+
+ZCode CLI 内置于桌面应用中，默认不会加到 `PATH`。用 `ZCODE_BIN` 指向内置的
+`zcode.cjs`：
+
+| 平台        | `ZCODE_BIN` 路径                                           |
+| ----------- | ---------------------------------------------------------- |
+| **macOS**   | `/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs` |
+| **Windows** | `%LOCALAPPDATA%\Programs\ZCode\resources\glm\zcode.cjs`    |
+| **Linux**   | 解压后的应用目录内：`<安装目录>/resources/glm/zcode.cjs`   |
+
+> 如果路径与实际安装不符，可用以下命令定位：
+>
+> ```bash
+> # macOS / Linux
+> find / -name zcode.cjs -path '*resources/glm*' 2>/dev/null
+> # Windows (PowerShell)
+> Get-ChildItem -Path $env:LOCALAPPDATA,$env:APPDATA,'C:\Program Files' -Recurse -Filter zcode.cjs -ErrorAction SilentlyContinue
+> ```
+
+## 环境变量
+
+| 变量              | 默认值           | 用途                                                                                                                                                                                                  |
+| ----------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ZCODE_BIN`       | `zcode`          | ZCode CLI 二进制文件路径或其 `.cjs` 入口                                                                                                                                                              |
+| `ZCODE_NODE`      | _（自动发现）_   | 显式指定运行 `ZCODE_BIN` 的 Node 二进制（必须支持 `node:sqlite`）                                                                                                                                     |
+| `ZCODE_MODEL`     | _（来自 config） | 覆盖当前使用的模型 id                                                                                                                                                                                 |
+| `ZCODE_BASE_URL`  | _（来自 config） | 覆盖 provider 的 base URL                                                                                                                                                                             |
+| `ZCODE_ACP_DEBUG` | _（未设置）      | 设为 `1` 可开启详细诊断日志（事件流、探测循环、状态更新）。默认安静——只输出警告类日志（后端管道错误、命令/权限失败、锁等待超时）。诊断桥接问题时开启；日志出现在 `Zed.log` 中，前缀为 `[zcode-acp]`。 |
+
+## ACP Registry
+
+本服务端兼容 [ACP Registry](https://agentclientprotocol.com/get-started/registry)。它在 `initialize` 时声明一个 `agent` 类型的认证方法——GLM API key 由 ZCode 后端从 `~/.zcode/v2/config.json` 读取，**编辑器侧无需配置任何凭据**。
+
+Registry 提交资产位于 [`registry/zcode-acp-server/`](registry/zcode-acp-server/)（`agent.json` + `icon.svg`）。包发布到 npm 后，将该目录复制到 [`agentclientprotocol/registry`](https://github.com/agentclientprotocol/registry) 的 fork 中并提 PR——CI 会校验 `agent.json` schema、图标，以及 `initialize` 返回的 `authMethods` 非空。
+
+## 开发
+
+```bash
+pnpm install
+pnpm build       # tsc → dist/
+pnpm typecheck   # tsc --noEmit
+pnpm lint        # eslint（警告为建议性质；错误会导致 CI 失败）
+pnpm test        # vitest
+pnpm format      # prettier on src/
+```
+
+CI 会在每次 push 和 pull request 时运行 `typecheck`、`lint`、`build` 和
+`test` —— 推送前请在本地跑一遍（见 [CONTRIBUTING.md](CONTRIBUTING.md)）。
+
+> **提示（Node 版本管理）**：本项目通过根目录的 `.node-version` 锁定 Node 22，
+> 推荐配合 [fnm](https://github.com/Schniz/fnm) 或 [nvm](https://github.com/nvm-sh/nvm)
+> 使用 —— 进入目录即自动切换到 Node 22。pnpm 的版本由本地环境（corepack）管理。
+
+## 架构
+
+服务端按 ACP 协议分层组织：
+
+- `backend/` —— ZCode 子进程客户端：spawn、reader-loop 多路复用、事件流监听、同步请求/响应
+- `translators/` —— 将 ZCode 事件转为 ACP `session/update` 通知（事件流 + 快照 diff）
+- `interaction/` —— 将 ZCode `interaction/*` 服务端请求桥接到 ACP，优先 `elicitation/create`，回退 `session/request_permission`（工具授权、ExitPlanMode、AskUserQuestion）
+- `handlers/` —— ACP 方法处理器（`session/new`、`session/prompt` 等）和 turn 引擎
+- `config/` —— model / mode / thought-level 的 configOptions 和运行时模型切换
+- `server.ts` —— 共享状态和处理器注册
+- `index.ts` —— 通过 ACP SDK 的 stdio 连接
+
+完整架构说明见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
+
+## 版本兼容性
+
+| ZCode CLI 版本 |  支持  | 说明                     |
+| :------------: | :----: | ------------------------ |
+| **>= 0.15.0**  |  完整  | 所有扩展方法可用         |
+| **>= 0.14.8**  |  完整  | 事件流推送、所有扩展方法 |
+|  **< 0.14.8**  | 不兼容 | 无事件流订阅能力         |
+
+## 文档
+
+- [架构](docs/ARCHITECTURE.md) —— 事件流、双路径去重、模块职责
+- [协议](docs/PROTOCOL.md) —— ZCode JSON-RPC 协议细节
+- [开发](docs/DEVELOPMENT.md) —— 本地开发、调试、新增扩展方法
+- [故障排查](docs/TROUBLESHOOTING.md) —— 常见问题排查
+
+## 贡献
+
+欢迎贡献！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解环境搭建、代码风格、
+commit 约定和 PR 检查清单。重要变更记录在 [CHANGELOG.md](CHANGELOG.md)。
+
+## 相关项目
+
+- [zcode-open-bridge](https://github.com/tizerluo/zcode-open-bridge) —— 一个社区 Python 实现，将 ZCode 接入 MCP/ACP 生态。本项目参考了它的桥接架构和若干处理策略。
+
+## 致谢
+
+- [Agent Client Protocol](https://agentclientprotocol.com/)（Apache 2.0）—— ACP 协议规范
+- [ZCode](https://zcode.z.ai) / [智谱 Z.AI](https://z.ai) —— GLM 模型与 ZCode CLI
+- [zcode-open-bridge](https://github.com/tizerluo/zcode-open-bridge) —— 参考实现，本项目的设计借鉴了它的桥接架构
+
+## 许可证
+
+Apache-2.0。本项目沿用上游 ACP 规范的同一许可证。
+
+## 免责声明
+
+本项目为独立的社区项目，与智谱 Z.AI 官方无任何隶属、认可或赞助关系。ZCode 是智谱 Z.AI 的产品。

package/dist/backend/client.d.ts

@@ -0,0 +1,103 @@
+/**
+ * ZCode subprocess client: spawn, read-loop multiplexer, async request/response.
+ *
+ * The ZCode app-server is launched as a subprocess (`zcode app-server --stdio`)
+ * speaking line-delimited JSON over stdio. A single async read loop demultiplexes
+ * inbound messages into three channels:
+ *   - responses (id, no method) → resolve the matching pending request promise
+ *   - server→client requests (id + method, id not pending) → server-request queue
+ *   - notifications (no id):
+ *       - `session/event` → routed to the registered session listener
+ *       - anything else   → general notification queue
+ *
+ * Process-group isolation: the subprocess is its own process-group leader
+ * (`detached: true`) so `close()` can kill the whole tree (zcode + its model
+ * workers) with `process.kill(-pid)` and leave no orphans.
+ */
+import { type ChildProcess } from "node:child_process";
+import type { ZcodeEvent, ZcodeInteractionPermissionParams, ZcodeInteractionUserInputParams, ZcodeResponse } from "./types.js";
+/** A server→client request that we must reply to. */
+export interface ServerRequest {
+    id: number;
+    method: string;
+    params: ZcodeInteractionPermissionParams | ZcodeInteractionUserInputParams | Record<string, unknown>;
+}
+/** Listener for `session/event` pushes on a given session. */
+export interface EventListener {
+    handleEvent(event: ZcodeEvent): void;
+}
+export declare class ZcodeBackend {
+    readonly proc: ChildProcess;
+    private readonly pending;
+    private readonly serverRequests;
+    private readonly listeners;
+    private readerDead;
+    /** Monotonic id for fire-and-forget sends (send()). Uses a high range to
+     *  avoid collisions with the server's request ids (low range). */
+    private sendIdCounter;
+    /** Watchdog process that kills the zcode group if this bridge dies (SIGKILL). */
+    private watchdog;
+    constructor(argv: string[], env: NodeJS.ProcessEnv);
+    /**
+     * Spawn a tiny detached watchdog that kills the zcode process group if this
+     * bridge process disappears.
+     *
+     * The detached/kill(-pid) cleanup in `close()` only runs when the bridge
+     * exits cleanly enough for the signal handlers to fire (SIGTERM/SIGINT/etc).
+     * If the bridge is SIGKILLed (Zed force-kill on reconnect, crash, OOM), the
+     * handler never runs and the zcode subprocess group is orphaned. The
+     * watchdog closes that gap: it polls the bridge pid every 2s and, once the
+     * bridge is gone, sends SIGKILL to the zcode process group, then exits.
+     *
+     * The watchdog is its own process-group leader (detached) and `unref`'d, so
+     * it never holds the event loop open and is not part of the zcode group it
+     * kills. It self-terminates as soon as the zcode process exits, so a normal
+     * shutdown leaves no lingering watchdog.
+     */
+    private startWatchdog;
+    private startReader;
+    private route;
+    private resolvePending;
+    private markReaderDead;
+    registerEventListener(zcodeSid: string, listener: EventListener): void;
+    unregisterEventListener(zcodeSid: string): void;
+    /** Non-blocking drain of pending server→client requests. */
+    pollServerRequests(): ServerRequest[];
+    /** Reply to a zcode server→client request with a result (id + result). */
+    sendReply(id: number, result: unknown): void;
+    /** Reply to a zcode server→client request with an error. */
+    sendError(id: number, code: number, message: string): void;
+    /** Fire-and-forget notification to ZCode (no id, no response). */
+    notify(method: string, params?: Record<string, unknown>): void;
+    /**
+     * Send a message with an id but WITHOUT registering a pending response
+     * (fire-and-forget). Mirrors Python's `_backend.send({"id": ..., ...})` for
+     * `session/stop`: some backends route by id presence, so carrying an id is
+     * more robust than a bare notify. If the backend replies, the reader's
+     * `resolvePending` finds no pending entry and safely discards it.
+     */
+    send(method: string, params?: Record<string, unknown>): void;
+    /**
+     * Synchronous request/response: register a pending promise, send, await.
+     * Other notifications arriving during the wait are routed async by the
+     * reader loop (they don't get swallowed).
+     *
+     * Returns `{error}` on dead backend, broken pipe, or timeout — never throws.
+     */
+    request(id: number, method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<ZcodeResponse>;
+    /**
+     * Kill the whole zcode process group and wait for it to die.
+     *
+     * SIGTERM → wait up to 3s → SIGKILL if still alive. Mirrors the Python
+     * `os.killpg` + `proc.wait(3)` + SIGKILL escalation. Note `proc.killed` is
+     * NOT set by `process.kill(-pid)` (group signal), so we track liveness via
+     * `exitCode === null` instead. Async so the caller can `await` a full reap
+     * before the parent exits (an unref'd timer could be skipped on fast exit,
+     * leaving orphans).
+     */
+    close(): Promise<void>;
+    /** Terminate the watchdog process if it is still running. */
+    private killWatchdog;
+    get isDead(): boolean;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/backend/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/backend/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAK9D,OAAO,KAAK,EACV,UAAU,EAEV,gCAAgC,EAChC,+BAA+B,EAC/B,aAAa,EACd,MAAM,YAAY,CAAC;AAQpB,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EACJ,gCAAgC,GAAG,+BAA+B,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChG;AAED,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;CACtC;AAED,qBAAa,YAAY;IACvB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAC7D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuB;IACtD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoC;IAC9D,OAAO,CAAC,UAAU,CAAS;IAC3B;sEACkE;IAClE,OAAO,CAAC,aAAa,CAAiB;IACtC,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAA6B;gBAEjC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU;IAmBlD;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,aAAa;IA+BrB,OAAO,CAAC,WAAW;IAqBnB,OAAO,CAAC,KAAK;IAiCb,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,cAAc;IAgBtB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,IAAI;IAItE,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAI/C,4DAA4D;IAC5D,kBAAkB,IAAI,aAAa,EAAE;IAKrC,0EAA0E;IAC1E,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI;IAY5C,4DAA4D;IAC5D,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAW1D,kEAAkE;IAClE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAS9D;;;;;;OAMG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAU5D;;;;;;OAMG;IACG,OAAO,CACX,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,SAAS,SAAQ,GAChB,OAAO,CAAC,aAAa,CAAC;IA+BzB;;;;;;;;;OASG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAsC5B,6DAA6D;IAC7D,OAAO,CAAC,YAAY;IAapB,IAAI,MAAM,IAAI,OAAO,CAEpB;CACF"}