Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ jobs:
uses: actions/checkout@v6
with:
repository: zai-org/ZCode
ref: 3c5b227649371507ddc4eb46ac5133afe6db1cab # 3.16.2 (untagged main)
ref: a9fe401eede6e6e5e01be9048679c206fe6f02d9 # v3.17.2
path: zcode-source
persist-credentials: false
- name: Install dependencies and generate build metadata
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ Identify the root cause and do not add ad hoc workarounds. Add backward compatib
- Limit implementations and proposed solutions to this Paseo plugin. Do not modify Paseo or ZCode itself, or require a fork. The only exception is the managed runtime's build-time patches in `patches/zcode/` (ADR 19): plain unified diffs against the pinned TypeScript source, applied with `git apply` (no fuzz) by the release workflow, and limited to hiding capabilities the provider cannot support. They must not change model requests, authentication or credentials, storage formats, the protocol or network endpoints. Each patch states its purpose, target and removal condition, and is removed once ZCode offers an official equivalent. Never patch installed files or alter behavior at launch. Building official ZCode from source is allowed for verification.

- Use `~/ghq/github.com/zai-org/ZCode` as the implementation reference. Record commit SHA and source paths; do not extract Electron/deb bundles for source investigation.
- Current source baseline: `3c5b227649371507ddc4eb46ac5133afe6db1cab` (3.16.2, an untagged upstream `main` sync commit; ADR 20). Verify vendored RPC/V4 source with `npm run check:zcode-source` and the runtime patches with `npm run check:zcode-patches -- /absolute/ZCode`. Keep `server/vendor/zcode` unformatted and retain its license/provenance.
- Current source baseline: `a9fe401eede6e6e5e01be9048679c206fe6f02d9` (3.17.2, upstream tag `v3.17.2`). Verify vendored RPC/V4 source with `npm run check:zcode-source` and the runtime patches with `npm run check:zcode-patches -- /absolute/ZCode`. Keep `server/vendor/zcode` unformatted and retain its license/provenance.
- The managed runtime is the default (ADR 15): Node.js from nodejs.org and the `zcode-runtime-v<version>-paseo.<n>` release of this repository, both pinned by SHA-256 in `server/runtime/pins.ts` and installed only when the user starts setup. Runtime setup RPCs never accept URLs, paths or versions from clients. `PASEO_ZCODE_RUNTIME` plus ordinary Node.js 24.14.0+ via `PASEO_ZCODE_NODE` override it; one variable alone is an error. Never fall back to Desktop/Electron.
- To ship a new ZCode version, update the source baseline (a tag, or an untagged `main` commit whose root `package.json` version equals the changelog release, per ADR 20), make every patch in `patches/zcode/` apply again (regenerate a rejected one against the new source and review it), push a `zcode-runtime-v<version>-paseo.<n>` tag so `.github/workflows/zcode-runtime-release.yml` builds, verifies on all managed platforms and publishes the archive, then pin the published SHA-256 and size. Never replace an existing release asset.
- `npm run test:stdio-runtime` uses the real runtime (override pair or managed runtime under `XDG_DATA_HOME`) with isolated data and a local model fixture. Resume guarantees require both Paseo's saved `mode` and `settings.plan_mode`; failures of this supported contract block release. Keep source SHA, distribution hashes, runtime versions and actual OS coverage separate.
Expand Down
2 changes: 1 addition & 1 deletion NOTICE.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ ZCode は統合 CLI を配布していないため、このリポジトリは `z

Node.js は利用者のマシンが nodejs.org の公式成果物を直接取得します。このリポジトリは Node.js を再配布しません。

`server/vendor/zcode` は [zai-org/ZCode](https://github.com/zai-org/ZCode/tree/3c5b227649371507ddc4eb46ac5133afe6db1cab) の RPC、V4 契約、wire 組み立てと純粋な差分適用、および必要なスキーマ依存を含みます。第一者コードは [上流 LICENSE](server/vendor/zcode/LICENSE) の Apache-2.0、RPC と wire codec の VS Code 由来部分は [MIT の通知](server/vendor/zcode/THIRD-PARTY-NOTICES.md) の条件を保持します。[上流 NOTICE](server/vendor/zcode/NOTICE.md) は全文を保持しており、上流製品全体の説明です。そこに記載された全機能・依存がプラグインへ同梱されることを意味しません。
`server/vendor/zcode` は [zai-org/ZCode](https://github.com/zai-org/ZCode/tree/a9fe401eede6e6e5e01be9048679c206fe6f02d9) の RPC、V4 契約、wire 組み立てと純粋な差分適用、および必要なスキーマ依存を含みます。第一者コードは [上流 LICENSE](server/vendor/zcode/LICENSE) の Apache-2.0、RPC と wire codec の VS Code 由来部分は [MIT の通知](server/vendor/zcode/THIRD-PARTY-NOTICES.md) の条件を保持します。[上流 NOTICE](server/vendor/zcode/NOTICE.md) は全文を保持しており、上流製品全体の説明です。そこに記載された全機能・依存がプラグインへ同梱されることを意味しません。

ファイルごとの出典・SHA-256、private workspace import の変更、第三者通知の抽出範囲を [provenance.json](server/vendor/zcode/provenance.json) に記録しています。取得・照合は `scripts/sync-zcode-source.mjs` で行います。`npm run build` はこれらのライセンス・通知を `dist/licenses/zcode` にも配置します。

Expand Down
11 changes: 6 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ This is an unofficial plugin. It is not endorsed or maintained by ZCode or Z.ai.
| Paseo | 0.15.0 or later; development SDK 0.15.3 |
| Plugin Node.js | 22.12.0 or later (the Paseo daemon's runtime) |
| Managed setup | darwin-arm64, linux-x64, linux-arm64, win-x64, win-arm64 |
| ZCode | Managed: 3.16.2 (release `3.16.2-paseo.1`) with Node.js 24.21.0. Overrides: stable Server 3.14.0+ / Agent 0.16.9+ with Node.js 24.14.0+ |
| ZCode | Managed: 3.17.2 (release `3.17.2-paseo.1`) with Node.js 24.21.0. Overrides: stable Server 3.14.0+ / Agent 0.16.9+ with Node.js 24.14.0+ |

## Installation

Expand All @@ -35,7 +35,7 @@ Open **Settings → Plugins → zcode-provider → Settings**. The screen has th
On the **Runtime** tab, choose **Download and install**. The screen lists every download, its SHA-256, size and license before you start. Setup runs on the machine hosting the daemon:

- Node.js 24.21.0 from nodejs.org.
- The ZCode runtime 3.16.2 from this repository's [releases](https://github.com/supermomonga/paseo-plugin-zcode-provider/releases/tag/zcode-runtime-v3.16.2-paseo.1) (`3.16.2-paseo.1`). ZCode does not publish its integrated CLI, so this is an **unofficial build** of the public source with the patches in [patches/zcode](patches/zcode) applied (ADR 19), made and verified by CI. The patches hide Computer Use, Browser Use and Visualize, which cannot run or render here. It is not endorsed or maintained by ZCode or Z.ai.
- The ZCode runtime 3.17.2 from this repository's [releases](https://github.com/supermomonga/paseo-plugin-zcode-provider/releases/tag/zcode-runtime-v3.17.2-paseo.1) (`3.17.2-paseo.1`). ZCode does not publish its integrated CLI, so this is an **unofficial build** of the public source with the patches in [patches/zcode](patches/zcode) applied (ADR 19), made and verified by CI. The patches hide Computer Use, Browser Use and Visualize, which cannot run or render here. It is not endorsed or maintained by ZCode or Z.ai.

Both archives are verified against SHA-256 values pinned in the plugin and extracted to the daemon user's data directory:

Expand Down Expand Up @@ -76,20 +76,21 @@ export PASEO_ZCODE_NODE=/absolute/path/to/node # ordinary Node.js 24.14.0

`PASEO_ZCODE_RUNTIME` must contain `server/remote/zcode-server.cjs`, `agent/zcode.cjs`, its provider configuration, and `package.json`. Setting only one variable is an error. Newer stable versions are allowed, including major versions; passing the minimum check does not certify compatibility. A terminal export does not change an already running Desktop application. Electron, `process.execPath` and Desktop discovery are never used.

Session environment variables are forwarded, subject to ZCode's own proxy, certificate and runtime environment handling.
Session environment variables are forwarded, subject to ZCode's own proxy, certificate and runtime environment handling. As Desktop does, the plugin sets `ZCODE_APP_VERSION` to the runtime's ZCode version, so model requests report it instead of the CLI's version.

The source baseline is `3c5b227649371507ddc4eb46ac5133afe6db1cab` (ZCode 3.16.2, an untagged upstream `main` commit; see ADR 20). The managed runtime passed the stdio runtime contract on all five managed platforms in CI. See the [verification record](docs/verification.md) for exact coverage.
The source baseline is `a9fe401eede6e6e5e01be9048679c206fe6f02d9` (ZCode 3.17.2, upstream tag `v3.17.2`). The managed runtime passed the stdio runtime contract on all five managed platforms in CI. See the [verification record](docs/verification.md) for exact coverage.

## Behavior

- Models and reasoning options come from ZCode. Editing modes are `build`, `edit`, `guarded` and `yolo`; `settings.plan_mode` is independent. `guarded` (ZCode's Autonomous mode, Server 3.15.1 or later) runs tools without approval but asks once, each time, before a command that ZCode's safety rules consider risky; it is not offered on older runtimes.
- Text, thoughts, tools, subagent progress, usage and history use V4 snapshots and deltas. Tool output is marked when ZCode truncates it. Usage is cumulative; repeated snapshots do not add it again.
- Text submitted during generation uses native guidance. Attachments use the native queue. Paseo reports one run across these native turns and completes it only after all accepted input has been consumed and foreground work has ended.
- Paseo sends every message typed in the app during a run as a steer that asks to clear pending permissions. The plugin queues it first, then declines pending permissions, questions and Plan approvals with their deny action until ZCode reads the message, including requests opened in the meantime. Requests that appear after it is read are left to the user. Declining a Plan approval in Plan mode ends ZCode's turn; the message then starts the next native turn in the same Paseo run (ADR 22).
- A failed turn reports a code classified from the attribution of ZCode's error: `MODEL_RATE_LIMITED`, `MODEL_AUTH_FAILED`, `MODEL_CONTEXT_EXCEEDED`, `MODEL_NETWORK_ERROR`, `MODEL_PROVIDER_ERROR` or `MODEL_REQUEST_FAILED` when the model provider or network failed, and `NATIVE_TURN_FAILED` otherwise. The message is the plugin's own text with the HTTP status and the provider's error code when known. The provider's own message, which can include a quota reset time, is not shown; Coding Plan reset times appear on Paseo's Usage screen (ADR 23).
- A failed turn reports a code classified from the attribution of ZCode's error: `MODEL_RATE_LIMITED`, `MODEL_AUTH_FAILED`, `MODEL_CONTEXT_EXCEEDED`, `MODEL_NETWORK_ERROR`, `MODEL_PROVIDER_ERROR`, `MODEL_CONTENT_FILTERED` or `MODEL_REQUEST_FAILED` when the model provider or network failed, and `NATIVE_TURN_FAILED` otherwise. The message is the plugin's own text with the HTTP status and the provider's error code when known. The provider's own message, which can include a quota reset time, is not shown; Coding Plan reset times appear on Paseo's Usage screen (ADR 23).
- Acceptance is reported once, after the native acknowledgement. Unknown delivery results are never automatically resent. Stop identifies the current native execution, disables automatic queue execution and removes pending input. A new explicit run enables the queue again.
- As in ZCode Desktop, successful hooks are not shown. A finished hook invocation appears once, as a notification, only when a hook was blocked, failed, timed out or was cancelled; context compaction also appears once, when it ends. Paseo appends every notification it receives, so progress is not reported. Model changes appear only when turned on (see [Timeline](#timeline)).
- Native permission IDs, option values, questions and Plan approval retain their meanings. Question auto-resolution is disabled for each owned Server. Workspace hook trust is reviewed through the official CLI; it is not represented as “allow once.”
- From ZCode 3.17, a project's own MCP servers start only after they are trusted in ZCode Desktop (Settings → MCP Servers); ZCode has no CLI command for it. A session that uses the project's MCP configuration shows a warning while any of them awaits trust. MCP servers that Paseo passes to a session replace ZCode's MCP configuration, as before, and are marked as the user's, so the project's trust review does not block them.
- Each session owns its Server process and environment. Metadata requests use temporary Servers. Closing stdin gives ZCode time to clean up before process termination.
- With **Release idle agents** (Host settings → Agents, on by default), Paseo closes an agent's session after an hour of inactivity and reopens it on the next message. The plugin keeps the session while ZCode still has a foreground turn, queued input, a pending question or approval, a running background command, subagent or workflow, or a goal that is active or being verified (ADR 25). A finished background command's result that ZCode has not yet delivered is not distinguishable and does not keep it. **Resume agents after restart** reopens agents interrupted by a host restart and sends the resume prompt. Both reopen the saved conversation with Paseo's saved mode and Plan settings ([ADR 14](docs/adr/0014-paseoの保存設定を再適用する復元を保証範囲とする.md)).

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -74,3 +74,5 @@ Chosen option: "公開 `main` 上の同期コミットのうち、ルート `pac
## More Information

2026-10-21 の確認:`git ls-remote` で `main` = `3c5b227`、タグは `v3.14.3`(`29628c9`)と `v3.15.1`(`aac4755`)だけ。`3c5b227` の親 `0a1fc56` が 3.16.1、その親 `aac4755` が 3.15.1。3.14.4、3.14.5、3.15.3 に対応するソースは公開されていない。上流が再びタグや GitHub Release を付けるようになったら、タグを基準とする運用に戻すかを見直す。詳細は[検証記録](../verification.md)を参照する。

2026-11-09 の見直し:上流は `v3.17.1`(`a60ba6a`)と `v3.17.2`(`a9fe401`)にタグと GitHub Release を付けた。どちらも、ルート `package.json` の版がタグの版と一致する。3.17.2 の基準はタグとし、ADR 15 の条件をそのまま満たす。版が一致するタグがあればタグを使う。タグの無い同期コミットを採る手順は、3.16.1 と 3.16.2 のようにタグが付かない版のために残す。変更履歴の 3.16.3 に対応するソースは無い。
Loading
Loading