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 @@ -30,7 +30,7 @@ jobs:
uses: actions/checkout@v6
with:
repository: getpaseo/paseo
ref: cafe4b01c8522ff39560241c5deb01427dc8dc5b # v0.12.0
ref: d91ae138cb931447635e94296023414a58bedcc5 # v0.15.3
path: paseo
persist-credentials: false
- name: Check out reference ZCode source
Expand Down
5 changes: 3 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,8 +59,9 @@ Identify the root cause and do not add ad hoc workarounds. Add backward compatib
- `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.
- `npm run test:native-restore` separately checks resume without explicit settings. The pinned upstream fails this unsupported path; retain its nonzero exit and run it when evaluating runtime updates. It is not a required CI or release condition (ADR 14).
- Account and provider settings go only through the official `oauth`, `setting` and `provider-settings` services of a plugin-owned Server, as Desktop does (ADR 17). Never read or write ZCode's credential or configuration files directly, store credentials in the plugin, or return API keys or native error messages to clients.
- On Paseo 0.11+, the provider's `status()` reports runtime discovery without starting a Server, and the `zcode` usage source reads Coding Plan quota only through `usage-stats.getEntitlementSnapshot` on the same Server (ADR 18). Register Paseo 0.11 APIs only when the daemon provides them, and import their types only from `@getpaseo/plugin/server`: older compilers reject `@getpaseo/plugin/server/usage`, even for types.
- The provider's `status()` reports runtime discovery without starting a Server, and the `zcode` usage source reads Coding Plan quota only through `usage-stats.getEntitlementSnapshot` on the same Server (ADR 18).
- Computer Use and Browser Use cannot run in the provider's standalone Server (ADR 19), and Visualize renders only in Desktop (ADR 21). `server/unsupported-capabilities.ts` defines what the bridge passes to every Server (`ZCODE_CUA_PRODUCT_HELPER=0` and `PASEO_ZCODE_SUPPRESSED_PLUGINS`) and the per-turn `toolDisallowlist`. Keep the official switches as well as the patch: `PASEO_ZCODE_RUNTIME` runtimes are unpatched.
- Plugin preferences are Paseo host settings defined in `shared/` and followed on the server through the `registerSettings()` handle (ADR 24). Paseo 0.9.0 is the minimum because older daemons cannot read them. Model change markers are hidden by default; whether one is shown is decided when it is first seen.
- Plugin preferences are Paseo host settings defined in `shared/` and followed on the server through the `registerSettings()` handle (ADR 24). Model change markers are hidden by default; whether one is shown is decided when it is first seen.
- Paseo 0.15.0 is the minimum (ADR 25); do not add branches for older daemons or import deprecated SDK entries such as `@getpaseo/plugin/client/react-native`. Paseo closes an idle session after an hour unless the provider vetoes it: `session.can_stop_runtime` answers from ZCode's V4 state and keeps the runtime while foreground work, input, interactions, commands, running background work or subagents, or an active/verifying goal remain. `resultPending` stays after delivery on the pinned source, so it does not count.
- Persistence handles use version 3. Do not migrate old Paseo handles or introduce Plan restoration storage.
- The plugin is published to npm only through the Version Bump and Release workflows (ADR 16); see `docs/development.md`. npm installation omits development dependencies, so keep runtime libraries other than Paseo's host modules (`@getpaseo/plugin/*`, `zod`) in `dependencies`. The `build` commands in `paseo-plugin.json` prepare Git checkouts only; `prepack` removes them from the npm package.
2 changes: 1 addition & 1 deletion NOTICE.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Node.js は利用者のマシンが nodejs.org の公式成果物を直接取得

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

開発 SDK は `@getpaseo/plugin@0.12.0` です。ビルドは `@getpaseo/plugin/server/provider` と `zod` を外部モジュールとして維持し、Paseo に解決させます。
開発 SDK は `@getpaseo/plugin@0.15.3` です。ビルドは `@getpaseo/plugin/server/provider` と `zod` を外部モジュールとして維持し、Paseo に解決させます。

`icon.svg` は [Paseo main c424f829 の glm-acp-agent.svg](https://github.com/getpaseo/paseo/blob/c424f82922fcd36aa9cc9e473644bca04417b420/packages/app/src/assets/acp-provider-icons/glm-acp-agent.svg) のコピーです。この SVG は [ACP Registry の glm-acp-agent/icon.svg](https://github.com/agentclientprotocol/registry/blob/f3826ddd6e35951ea9b7fd0cf43c35a30c3c64cd/glm-acp-agent/icon.svg) とバイト単位で一致します。ACP Registry は Apache-2.0 で配布されており、その [LICENSE](vendor/acp-registry/LICENSE) を保持しています。アイコンは変更していません。商標への権利や公式の承認を示すものではありません。

Expand Down
17 changes: 9 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ This is an unofficial plugin. It is not endorsed or maintained by ZCode or Z.ai.

| Setting | Requirement |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Paseo | 0.9.0 or later; development SDK 0.12.0 |
| 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+ |
Expand All @@ -24,9 +24,9 @@ paseo plugin add npm:paseo-plugin-zcode-provider
paseo plugin ls
```

You can also paste `npm:paseo-plugin-zcode-provider` into **Settings → Plugins → Plugin source**. npm packages require Paseo 0.9.0 or later and npm on the daemon host. Paseo installs the released version and compiles the plugin. Update with `paseo plugin update zcode-provider`. Plugins execute with the daemon user's permissions.
You can also paste `npm:paseo-plugin-zcode-provider` into **Settings → Plugins → Plugin source**. npm packages require npm on the daemon host. Paseo installs the released version and compiles the plugin. Update with `paseo plugin update zcode-provider`. Plugins execute with the daemon user's permissions.

To follow the `main` branch instead, install the Git repository with `paseo plugin add github:supermomonga/paseo-plugin-zcode-provider` (Paseo 0.9.0 or later). Since Paseo 0.11.0, the form without `github:` looks the plugin up in Paseo's plugin registry, which does not list it. Paseo prepares the checkout with `npm ci`.
To follow the `main` branch instead, install the Git repository with `paseo plugin add github:supermomonga/paseo-plugin-zcode-provider`. The form without `github:` looks the plugin up in Paseo's plugin registry, which does not list it. Paseo prepares the checkout with `npm ci`.

## Setup

Expand Down Expand Up @@ -55,15 +55,15 @@ The **Account** tab uses ZCode's own account and provider services, the same one
- **Sign in**: choose Z.ai (international) or BigModel (China) and press **Sign in**. The sign-in page opens in your browser; the link is also shown, so you can finish on any device. The daemon receives the result, then selects the account's Coding Plan unless a plan is already chosen. The **Plans** section shows which of the account's plans (Coding Plan, Start Plan) are available. ZCode allows one signed-in account at a time.
- **Model providers**: add any number of providers that use an API key, from a ZCode template (Z.ai, BigModel, Kimi, MiniMax, DeepSeek, Alibaba Cloud, OpenAI, Anthropic, xAI, OpenRouter and others) or a custom endpoint with its base URL, API format and model IDs. Providers and models can be turned off, edited and deleted.

API keys are sent to ZCode, which stores them as Desktop does, and are never shown again. The plugin itself stores no credentials. Afterwards, choose **ZCode** when creating an agent; the model list is refreshed after each change on Paseo 0.9 or later.
API keys are sent to ZCode, which stores them as Desktop does, and are never shown again. The plugin itself stores no credentials. Afterwards, choose **ZCode** when creating an agent; the model list is refreshed after each change.

### Timeline

ZCode adds a line when a turn runs on a different model than the previous turn, such as `Model switched magpie/GLM-5.3-Flash → magpie/auto/glm-5.3-flash`. These lines are hidden by default; turn on **Show model changes** on the **Timeline** tab to show them. The setting is stored by Paseo on the daemon host. It decides each line when the line first arrives: lines already shown stay, and lines that arrived while it was off are not added later. A reopened agent shows its history with the current setting (ADR 24).

### Coding Plan usage

On Paseo 0.11 and later, Paseo's **Usage** screen and sidebar usage summary show a **ZCode** card for the signed-in account's Individual Coding Plan (Z.ai or BigModel). It lists the 5-hour, weekly, monthly tool-call and ZCode MCP quotas with their reset times, as ZCode Desktop does. The plugin asks ZCode's official usage service for this plan only, on the same ZCode Server as the Account tab. The service never uses an API key from the environment. Team Plan and Start Plan are not shown. Paseo 0.12.0 does not yet show usage in a ZCode agent's popover.
Paseo's **Usage** screen and sidebar usage summary show a **ZCode** card for the signed-in account's Individual Coding Plan (Z.ai or BigModel). It lists the 5-hour, weekly, monthly tool-call and ZCode MCP quotas with their reset times, as ZCode Desktop does. The plugin asks ZCode's official usage service for this plan only, on the same ZCode Server as the Account tab. The service never uses an API key from the environment. Team Plan and Start Plan are not shown. Nothing is requested while **Check usage** is off for the host. Paseo 0.15.3 does not yet show usage in a ZCode agent's popover.

### Using your own runtime

Expand All @@ -86,13 +86,14 @@ The source baseline is `3c5b227649371507ddc4eb46ac5133afe6db1cab` (ZCode 3.16.2,
- 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 0.11'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` 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.”
- 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)).

The plugin uses ZCode's own skills, MCP configuration and tools. Browser Use and Computer Use cannot run in the plugin's ZCode, even when ZCode Desktop has them enabled: the Computer Use helper accepts only the signed Desktop app, and only Desktop provides browsers. ZCode's Visualize (interactive views in the conversation) renders only in Desktop. The plugin therefore hides all three from the model (ADR 19, ADR 21); Desktop is not affected. Generic rewind, independent Paseo child agents, hook-review UI and Goal/Workflow controls are outside this migration. `prompt.output_schema`, custom system prompts and `persist:false` are unsupported. A system prompt makes session creation fail with `INVALID_CONFIGURATION` and a message explaining why, including one appended by Paseo's Orchestration → System prompt setting or by another plugin that adds one to new agents. MCP `alwaysLoad` is unsupported; stdio MCP commands must be absolute paths. Provider options are unsupported: in Paseo 0.11 and later, `agents.providers.zcode.options` in Paseo's `config.json` makes sessions fail with `INVALID_CONFIGURATION`, and the `command` and `env` overrides there are not applied. Paseo does not show context usage reported before the first turn, and the plugin adds no substitute display; Coding Plan quota appears in Paseo 0.11's Usage screen (see [Coding Plan usage](#coding-plan-usage)).
The plugin uses ZCode's own skills, MCP configuration and tools. Browser Use and Computer Use cannot run in the plugin's ZCode, even when ZCode Desktop has them enabled: the Computer Use helper accepts only the signed Desktop app, and only Desktop provides browsers. ZCode's Visualize (interactive views in the conversation) renders only in Desktop. The plugin therefore hides all three from the model (ADR 19, ADR 21); Desktop is not affected. Generic rewind, independent Paseo child agents, hook-review UI and Goal/Workflow controls are outside this migration. `prompt.output_schema`, custom system prompts and `persist:false` are unsupported. A system prompt makes session creation fail with `INVALID_CONFIGURATION` and a message explaining why, including one appended by Paseo's Orchestration → System prompt setting or by another plugin that adds one to new agents. MCP `alwaysLoad` is unsupported; stdio MCP commands must be absolute paths. Provider options are unsupported: `agents.providers.zcode.options` in Paseo's `config.json` makes sessions fail with `INVALID_CONFIGURATION`, and the `command` and `env` overrides there are not applied. Paseo does not show context usage reported before the first turn, and the plugin adds no substitute display; Coding Plan quota appears in Paseo's Usage screen (see [Coding Plan usage](#coding-plan-usage)).

## Persistence

Expand All @@ -104,7 +105,7 @@ New conversations support listing, resume and paged V4 history. From ZCode 3.16,

## Diagnostics

**Settings → Plugins → zcode-provider → Diagnostics** shows whether the managed runtime or the environment override is in use, the runtime and Node.js paths and versions, Server/Agent versions and hashes, minimum-version assessment and mapping location. The screen is read-only. Its optional version check does not prove that authentication or a model call succeeds. On Paseo 0.11 and later, **Settings → Providers** also shows ZCode as not installed until the runtime is set up and supported. Its diagnostic lists the runtime source, Server, Agent and Node.js versions and platform, or the reason the runtime cannot be used. This check reuses its result for 30 seconds and does not start ZCode, so sign-in problems still appear when a session starts.
**Settings → Plugins → zcode-provider → Diagnostics** shows whether the managed runtime or the environment override is in use, the runtime and Node.js paths and versions, Server/Agent versions and hashes, minimum-version assessment and mapping location. The screen is read-only. Its optional version check does not prove that authentication or a model call succeeds. **Settings → Providers** also shows ZCode as not installed until the runtime is set up and supported. Its diagnostic lists the runtime source, Server, Agent and Node.js versions and platform, or the reason the runtime cannot be used. This check reuses its result for 30 seconds and does not start ZCode, so sign-in problems still appear when a session starts.

```bash
paseo plugin logs zcode-provider
Expand Down
Loading
Loading