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
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ This plugin connects Paseo's public Provider API to the official stdio Services

- `index.server.ts` / `index.client.tsx`: Server and settings UI registration.
- `server/`: Provider, sessions, and persistence. `discovery/` locates installations; `runtime/` pins and installs the managed runtime; `host/` and `protocol/` handle startup, communication, and validation.
- `client/`: React Native Settings (Runtime and Account tabs) and Diagnostics screens. `shared/` contains types and contracts shared by the server and client.
- `client/`: React Native Settings (Runtime, Account and Timeline tabs) and Diagnostics screens. `shared/` contains types and contracts shared by the server and client.
- `test/`: Integration tests and `fake-host.ts`. Unit tests also live in `server/`.
- `scripts/`: Build, upstream integration, and runtime verification scripts. `docs/` contains development procedures, verification records, and ADRs. Images live in `images/` and `icon.svg`.

Expand Down Expand Up @@ -61,5 +61,6 @@ Identify the root cause and do not add ad hoc workarounds. Add backward compatib
- 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.
- 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.
- 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.
10 changes: 7 additions & 3 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.8.0 or later; development SDK 0.12.0 |
| Paseo | 0.9.0 or later; development SDK 0.12.0 |
| 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 @@ -30,7 +30,7 @@ To follow the `main` branch instead, install the Git repository with `paseo plug

## Setup

Open **Settings → Plugins → zcode-provider → Settings**. The screen has two tabs: **Runtime** installs and removes the runtime, and **Account** signs in and manages model providers.
Open **Settings → Plugins → zcode-provider → Settings**. The screen has three tabs: **Runtime** installs and removes the runtime, **Account** signs in and manages model providers, and **Timeline** chooses what ZCode agents add to the timeline.

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:

Expand All @@ -57,6 +57,10 @@ The **Account** tab uses ZCode's own account and provider services, the same one

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.

### 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.
Expand Down Expand Up @@ -84,7 +88,7 @@ The source baseline is `3c5b227649371507ddc4eb46ac5133afe6db1cab` (ZCode 3.16.2,
- 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).
- 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.
- 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.

Expand Down
6 changes: 5 additions & 1 deletion client/settings.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,12 @@ import { Pressable, Text, View } from "react-native";
import type { PluginSurfaceProps } from "@getpaseo/plugin/client";
import { AccountTab } from "./account";
import { RuntimeTab } from "./runtime";
import { TimelineTab } from "./timeline";

const TABS = [
{ id: "runtime", label: "Runtime" },
{ id: "account", label: "Account" },
{ id: "timeline", label: "Timeline" },
] as const;
type Tab = (typeof TABS)[number]["id"];

Expand Down Expand Up @@ -76,8 +78,10 @@ export function SettingsScreen(props: PluginSurfaceProps) {
<Tabs value={tab} onChange={setTab} theme={props.theme} />
{tab === "runtime" ? (
<RuntimeTab {...props} />
) : (
) : tab === "account" ? (
<AccountTab {...props} onOpenRuntime={() => setTab("runtime")} />
) : (
<TimelineTab {...props} />
)}
</View>
);
Expand Down
78 changes: 78 additions & 0 deletions client/timeline.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
import { useCallback } from "react";
import { type PluginSurfaceProps, useSettings } from "@getpaseo/plugin/client";
import {
SettingsAction,
SettingsCard,
SettingsRow,
SettingsSection,
SettingsSwitch,
} from "@getpaseo/plugin/client/ui";
import { zcodeTimelineSettings } from "../shared/timeline";
import { Value } from "./value";

const LABEL = "Show model changes";

export function TimelineTab({ theme, layout }: PluginSurfaceProps) {
const settings = useSettings(zcodeTimelineSettings);
const toggle = useCallback(
(showModelChanges: boolean) => {
if (settings.status === "ready")
void settings.save(
{ ...settings.values, showModelChanges },
settings.revision,
);
},
[settings],
);

if (settings.status === "loading")
return (
<SettingsSection title="Timeline">
<SettingsCard>
<SettingsRow label={LABEL}>
<Value
color={theme.colors.foregroundMuted}
compact={layout.compact}
>
Loading…
</Value>
</SettingsRow>
</SettingsCard>
</SettingsSection>
);
if (settings.status !== "ready")
return (
<SettingsSection title="Timeline">
<SettingsCard>
<SettingsRow label={LABEL} error={settings.error} />
<SettingsAction
label="Try again"
actionLabel="Reload"
onPress={() => void settings.reload()}
/>
{settings.status === "invalid" ? (
<SettingsAction
label="Restore the default"
actionLabel="Reset"
disabled={settings.saving}
onPress={() => void settings.reset()}
/>
) : null}
</SettingsCard>
</SettingsSection>
);
return (
<SettingsSection title="Timeline">
<SettingsCard>
<SettingsSwitch
label={LABEL}
hint="Adds a line when ZCode runs a turn on a different model than the previous turn. Applies to lines that arrive after the change; reopened agents show their history with the current setting."
value={settings.values.showModelChanges}
disabled={settings.saving}
error={settings.saveError}
onValueChange={toggle}
/>
</SettingsCard>
</SettingsSection>
);
}
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ links:
kind: amendedby
- target: 18
kind: amendedby
- target: 24
kind: amendedby
---

# 設定画面は読み取り専用の診断に限定しホスト状態を専用RPCで返す
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
---
number: 24
title: モデル切り替えの表示をPaseoの設定APIで選べるようにし最低要件を0.9.0に上げる
status: accepted
date: 2026-11-09
links:
- target: 8
kind: amends
---

# モデル切り替えの表示をPaseoの設定APIで選べるようにし最低要件を0.9.0に上げる

## Context and Problem Statement

ZCode は、ターンのプロバイダーとモデルが直前のターンと違うとき、そのターンの前に `modelChange` の `timelineMarker` 行を置く(3c5b227 の `apps/zcode-cli/packages/bootstrap/src/zcode-protocol-v4/product-projection.ts` の `onTurnStarted`)。プラグインはこれを Paseo の通知に変換していた。Issue #83 では、ターンのたびにこの行が二つずつ増えて会話が読みにくいと報告され、表示をやめるよう求められた。Paseo は受け取った通知を後から消せない。セッションで選んでいるモデルは Paseo のヘッダーに出る。

ADR 8 は、Paseo 0.8.0 には daemon 側から保存値を読む API が無いので設定値を保存しないとし、その API が公開されたら見直すとした。Paseo 0.9.0 から `server.registerSettings()` が `read()` と `subscribe()` を持つハンドルを返す。プラグインの最低要件は 0.8.0 で、0.8.0 の `registerSettings()` は何も返さない。

## Decision Drivers

- 既定では会話にこの行を出さず、必要な人は出せるようにする。
- 設定は Paseo の公式の保存と UI の仕組みで扱い、独自の保存先を作らない。
- 画面で変えた設定が、対応するすべての Paseo で実際に効くようにする。
- Paseo の会話で、行が後から末尾に並んだり、重なったりしないようにする。

## Considered Options

- マーカーを常に出さない。
- Paseo の設定 API で表示を選べるようにし、最低要件を 0.9.0 に上げる。
- Paseo の設定 API で表示を選べるようにし、最低要件は 0.8.0 のままにする。

## Decision Outcome

Chosen option: 「Paseo の設定 API で表示を選べるようにし、最低要件を 0.9.0 に上げる」。報告された不満を既定で解消しつつ、本当にモデルが変わったことを知りたい人の手段を残し、保存と画面を Paseo の仕組みだけで実現できるため。

- `shared/timeline.ts` に `defineSettings` でホスト単位の文書 `timeline`(版 1、`showModelChanges` の既定は `false`)を定義する。サーバーは `registerSettings()` のハンドルの `read()` と `subscribe()` で現在の値を追う。最初の読み込みが終わるまでと、保存値が不正な間は既定値を使う。
- 設定画面に Runtime・Account とは別の Timeline タブを置き、`useSettings` のスイッチで切り替える。不正な保存値は既定値に戻せる。
- 表示するかどうかは、マーカーを最初に見た時点の設定で決める。出した行はそのまま残し、非表示の間に来た行は後から出さない。セッションを開き直したときは、その時点の設定で履歴を作る。
- 行の文言は ZCode Desktop に合わせ、最初のモデルは `Using provider/model`、切り替えは `Model switched provider/model → provider/model` とする。推論レベルは出さない。
- `paseo-plugin.json` の最低要件を `>=0.9.0` に上げる。

### Consequences

- Good, because 既定の会話から、毎ターン増える行が無くなる。
- Good, because 設定の保存・不正値の扱い・クライアント間の同期を Paseo が担い、プラグインは保存先を持たない。
- Bad, because Paseo 0.8 系では新しい版を導入できなくなる。
- Bad, because 既定ではモデルが本当に切り替わったことも会話からは分からない。
- Bad, because 設定を変えても、すでに会話にある行は変わらない。

### Confirmation

`test/provider.test.ts` で、最初に見た時点の設定で表示が決まることと、開き直したときの履歴がその時点の設定に従うことを確認する。`server/timeline-settings.test.ts` で、既定値、保存値の追従、不正値、最初の読み込みより新しい保存を確認する。`npm run test:upstream` は実際のコンパイラで設定の登録を確認する。

## Pros and Cons of the Options

### マーカーを常に出さない

- Good, because 設定も画面も要らない。
- Bad, because ZCode がモデルを切り替えたことを Paseo で知る手段が無くなる。

### 設定 API で選べるようにし、最低要件を 0.9.0 に上げる

- Good, because 画面のスイッチが、対応するすべての Paseo で効く。
- Bad, because Paseo 0.8 系の利用者は更新できない。

### 設定 API で選べるようにし、最低要件は 0.8.0 のままにする

- Good, because Paseo 0.8 系でも新しい版を導入できる。
- Bad, because 0.8 系では画面のスイッチが保存されるだけで効かない。画面からはそれを見分けられない。

## More Information

ADR 8 のうち、設定値を保存しないという部分を変える。診断画面の項目と秘匿方針はそのままとする。Paseo 側の根拠は `public-docs/plugins/reference.md` の Persisted values と、v0.8.0 と v0.9.0 の `packages/plugin/src/server/contracts.ts`。[Issue #83](https://github.com/supermomonga/paseo-plugin-zcode-provider/issues/83)。ZCode が `modelChange` を出す条件を変えたとき、または Paseo が受け取った行を後から消せるようになったときに見直す。
1 change: 1 addition & 0 deletions docs/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,3 +21,4 @@
* [21. Desktop専用のvisualizeプラグインもADR 19の抑止対象に加える](0021-desktop専用のvisualizeプラグインもadr-19の抑止対象に加える.md)
* [22. Paseoが求めるときは受け付けたSteerが読まれるまで保留中の権限確認を拒否する](0022-paseoが求めるときは受け付けたsteerが読まれるまで保留中の権限確認を拒否する.md)
* [23. ターンの失敗はV4のlastErrorのattributionで分類したコードと固定の文言で伝える](0023-ターンの失敗はv4のlasterrorのattributionで分類したコードと固定の文言で伝える.md)
* [24. モデル切り替えの表示をPaseoの設定APIで選べるようにし最低要件を0.9.0に上げる](0024-モデル切り替えの表示をpaseoの設定apiで選べるようにし最低要件を0-9-0に上げる.md)
Loading
Loading