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
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,7 @@ 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).
- 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.
- 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.”
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ links:
kind: amendedby
- target: 13
kind: amendedby
- target: 23
kind: amendedby
---

# 最低バージョンと実行時検証でZCodeの更新を許可する
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
---
number: 23
title: ターンの失敗はV4のlastErrorのattributionで分類したコードと固定の文言で伝える
status: accepted
date: 2026-11-09
links:
- target: 7
kind: amends
---

# ターンの失敗はV4のlastErrorのattributionで分類したコードと固定の文言で伝える

## Context and Problem Statement

ZCode のターンが失敗すると、Paseo には `[System Error] ZCode turn failed` と `code: NATIVE_PROTOCOL_ERROR` だけが表示されていた([Issue #86](https://github.com/supermomonga/paseo-plugin-zcode-provider/issues/86))。プラグインは失敗した turnHeader だけを見て、固定の文言とコードを返していた。利用者もオーケストレーターのエージェントも、利用上限・認証・ネットワークのどれが原因かを判断できなかった。`NATIVE_PROTOCOL_ERROR` は通信の形式の誤りを表すコードなので、プラグインの不具合のようにも見えた。

3c5b227 の CLI は、TurnError を受けると、turnHeader を `failed` にするのと同じフレームで `control.lastError`(`sessionErrorInfoSchema`)を設定し、次のターンの開始時に `null` に戻す(`product-projection.ts`)。Desktop の `ChatErrorBanner` はこの値を表示する。`lastError` には ZCode の `message`・`detail`・`underlyingErrorMessage` と、列挙値と数値からなる `attribution`(`source`、`reason`、`errorPhase`、`exceptionKind`、`statusCode`、`providerErrorCode`、`retryable` など)がある。

管理下ランタイム 3.16.2 で、ローカルのモデルから GLM の 429(エラーコード 1310)を返して確認した。`message` はプロバイダーの原文(週・月の利用上限とリセット時刻を伝える中国語の文)、`code` は `"1310"`、`attribution.reason` は `rate_limited`、`statusCode` は 429 だった。`recoverable` は `true` で、`attribution.retryable: false` と食い違っていた。

ADR 7 は、ネイティブのエラーメッセージを ProviderError.diagnostic とログに出さないと決めている。プロバイダーのエラー文には、プロバイダーによって API キーの一部やリクエストの内容が入ることがある。Paseo はターンの失敗の文言・コード・診断をタイムラインに保存し、オーケストレーターのエージェントにも渡す(`agent-manager.ts` の `formatTurnFailedMessage`)。

## Decision Drivers

- 利用者とエージェントが、失敗の種類と次に取る行動を判断できるようにする。
- ADR 7 のとおり、ネイティブの文字列を出力に含めない。
- ZCode が公式に投影する V4 の状態だけを使う。旧プロトコルのイベントやエラー文の照合には頼らない。

## Considered Options

- `lastError.attribution` で分類したコードと、プラグインの固定の文言を返す。
- Desktop と同じく `lastError.message`(プロバイダーの原文)を表示する。
- 旧プロトコルの `turn.failed` イベントのエラー詳細を使う(Issue #86 の提案)。

## Decision Outcome

Chosen option: 「`lastError.attribution` で分類したコードと、プラグインの固定の文言を返す」。ADR 7 を変えずに、失敗の種類と対処を伝えられるため。

- ターンが失敗したら、そのフレームの `control.lastError` を読む。分類には `attribution.source`(無ければ `lastError.source`)と `attribution.reason` だけを使う。`lastError.code` にはプロバイダー固有のコードがそのまま入ることがあるので使わない。
- `source` が `provider` か `network` のとき、`reason`(ZCode の `ModelFailureReason`)を次のコードに対応付ける。`MODEL_RATE_LIMITED`(`rate_limited`、`offpeak_queued`)、`MODEL_AUTH_FAILED`(`auth_failed`、`auth_refresh`、`provider_not_configured`)、`MODEL_CONTEXT_EXCEEDED`(`context_exceeded`)、`MODEL_NETWORK_ERROR`(`network_error`、`timeout`、`stream_idle_timeout`、`stale_connection`、`proxy_error`、`tls_error`)、`MODEL_PROVIDER_ERROR`(`server_error`、`provider_overloaded`)。それ以外の `reason` は、`network` なら `MODEL_NETWORK_ERROR`、`provider` なら `MODEL_REQUEST_FAILED` とする。
- `runtime`・`tool` の失敗と、`lastError` が無い失敗は `NATIVE_TURN_FAILED`(`ZCode turn failed.`)とする。ターンの失敗に `NATIVE_PROTOCOL_ERROR` は使わない。
- 文言はプラグインの固定の英文とし、HTTP ステータスと、数字だけか英字の語だけからなるプロバイダーのエラーコードを添える。利用上限では、Coding Plan のリセット時刻を Paseo 0.11 以降の Usage 画面で確認できると案内する(ADR 18)。
- ProviderError.diagnostic に `stage: "turn"` と `failure` を加える。`failure` には、許可リストに一致した `source`・`reason`・`errorPhase`・`exceptionKind`、100〜599 の `statusCode`、上記の条件を満たす `providerErrorCode`、`retryable` だけを入れる。`providerId`・`modelId` は利用者が付けた名前を含みうるので入れない。

### Consequences

- Good, because 利用上限・認証・ネットワークなどの失敗を、コードと文言で見分けられる。
- Good, because ネイティブの文字列は、文言にも診断にも入らない。
- Bad, because プロバイダーの原文にしか無い情報(Coding Plan 以外の利用上限のリセット時刻など)は伝わらない。
- Bad, because ZCode が `reason` の語彙を変えると、分類が `MODEL_REQUEST_FAILED` などの汎用のコードに落ちる。

### Confirmation

`server/turn-failure.test.ts` で、各 `reason` と `source` の分類、ネイティブの文字列が文言と診断に入らないこと、報告できないプロバイダーのエラーコードを落とすことを確認する。`test/provider.test.ts` で、3.16.2 の 429 と同じ形の `lastError` が分類されて Paseo の `session.turn` に届くことと、`lastError` が無いときの汎用の失敗を確認する。`npm run test:stdio-runtime` は、ローカルのモデルが 429(1310)を返したときに `MODEL_RATE_LIMITED` が届き、原文が含まれず、次のプロンプトが完了することを実ランタイムで確認する。

## Pros and Cons of the Options

### 分類したコードと固定の文言を返す

- Good, because ADR 7 の範囲で実現でき、表示する内容をプラグインが決められる。
- Bad, because 固定の文言では、プロバイダーごとの事情までは表せない。

### `lastError.message` を表示する

- Good, because Desktop と同じ内容になり、リセット時刻などがそのまま分かる。
- Bad, because ADR 7 の見直しが要る。プロバイダーの原文がタイムラインに保存され、エージェントにも渡る。原文はプロバイダーの言語(GLM なら中国語)で返る。

### 旧プロトコルの `turn.failed` イベントを使う

- Good, because エラー詳細の構造は `lastError` と同じである。
- Bad, because ADR 13 によりプラグインは V4 の会話状態だけを使い、旧プロトコルのイベントを購読していない。同じ内容は V4 の `lastError` に公式に投影されている。

## More Information

ADR 7 の診断の方針を補う。ZCode 側の根拠は 3c5b227 の `apps/zcode-cli/packages/bootstrap/src/zcode-protocol-v4/product-projection.ts`(TurnError の投影と、ターン開始時の消去)、`packages/shared/src/zcode-protocol-v4/snapshot.ts`(`sessionErrorInfoSchema`、`errorAttributionSchema`)、`apps/zcode-cli/packages/contracts/src/model/index.ts`(`ModelFailureReason`)、`apps/zcode-cli/packages/adapters/src/model/failure-provider-business-codes.ts`、`packages/ui/src/ChatErrorBanner.tsx`。Paseo 側は `packages/server/src/server/agent/agent-manager.ts` の `formatTurnFailedMessage`。ZCode が `lastError` にリセット時刻などを構造化して加えたとき、または Paseo がエラーコードに応じた表示を持ったときに見直す。
1 change: 1 addition & 0 deletions docs/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,3 +20,4 @@
* [20. タグの無い上流の同期コミットをpackage versionで特定してZCodeのソース基準にする](0020-タグの無い上流の同期コミットをpackage-versionで特定してzcodeのソース基準にする.md)
* [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)
4 changes: 2 additions & 2 deletions docs/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ npm run check:zcode-source -- ~/ghq/github.com/zai-org/ZCode
npm run test:upstream -- /absolute/path/to/paseo
```

`test:upstream` uses Paseo's actual plugin compiler, Git preparation and Provider adapter. Use commit `cafe4b01c8522ff39560241c5deb01427dc8dc5b` (0.12.0), matching the installed development SDK. It checks clean npm preparation of a Git checkout both with `NODE_ENV` unset and `production`, installation of the `npm pack` tarball with Paseo's npm acquisition options, server/client registration and the provider icon of both, V4 timeline, guidance, attachment queue aggregation, stop, provider replacement, history and Plan configuration on resume. The adapter fixture uses the official V4 schemas and delta application; it does not prove native behavior.
`test:upstream` uses Paseo's actual plugin compiler, Git preparation and Provider adapter. Use commit `cafe4b01c8522ff39560241c5deb01427dc8dc5b` (0.12.0), matching the installed development SDK. It checks clean npm preparation of a Git checkout both with `NODE_ENV` unset and `production`, installation of the `npm pack` tarball with Paseo's npm acquisition options, server/client registration and the provider icon of both, V4 timeline, guidance, attachment queue aggregation, a classified turn failure, stop, provider replacement, history and Plan configuration on resume. The adapter fixture uses the official V4 schemas and delta application; it does not prove native behavior.

## Source of truth

Expand Down Expand Up @@ -73,7 +73,7 @@ The baseline's remote terminal service cannot locate the integrated distribution

`npm run test:usage-runtime` runs the provider's `status()` and the Coding Plan usage source (ADR 18) against the same runtime and existing ZCode sign-in, and validates the results with Paseo's `ProviderStatusSchema` and `UsageReportSchema`. ZCode requests the account's quota from Z.ai or BigModel; the check writes no settings and prints no account names or keys.

`npm run test:stdio-runtime` exercises the real extracted Server and Agent against a deterministic **local HTTP model fixture**, without billable API calls. It isolates HOME, ZCode settings, the SQLite database, temp sockets, workspace and plugin mappings. It checks catalog, draft, Bash, acknowledgements, completion, paged replay, mode/Plan restore **with both saved Paseo settings**, questions, tool approval, targeted stop and restart, session listing and owned Agent exit after Server SIGKILL. The test captures the settings before shutdown, closes the Server, opens a separate connection and requires the restored settings to be reported before `session.ready`. Any failed assertion exits nonzero. It deletes test data after cleanup. Loopback and Unix sockets require execution outside a restrictive network sandbox.
`npm run test:stdio-runtime` exercises the real extracted Server and Agent against a deterministic **local HTTP model fixture**, without billable API calls. It isolates HOME, ZCode settings, the SQLite database, temp sockets, workspace and plugin mappings. It checks catalog, draft, Bash, acknowledgements, completion, paged replay, mode/Plan restore **with both saved Paseo settings**, questions, tool approval, targeted stop and restart, a provider quota failure (HTTP 429 with GLM's code 1310) that must arrive as `MODEL_RATE_LIMITED` without the provider's text and a following completed turn, session listing and owned Agent exit after Server SIGKILL. The test captures the settings before shutdown, closes the Server, opens a separate connection and requires the restored settings to be reported before `session.ready`. Any failed assertion exits nonzero. It deletes test data after cleanup. Loopback and Unix sockets require execution outside a restrictive network sandbox.

`npm run test:native-restore` adds a strict check of cold resume **without explicit settings** to the same isolated runner. It fails on the pinned source because ZCode replaces saved execution state with an old message mode and Plan OFF. This path is outside the supported restoration contract, so this command is separate from required CI and release conditions; there is no `continue-on-error` or blanket error suppression. Run it when evaluating official runtime updates and record the outcome. A successful upstream check is evidence for reconsidering the guarantee, not an automatic expansion of it. See [ADR 14](adr/0014-paseoの保存設定を再適用する復元を保証範囲とする.md).

Expand Down
30 changes: 30 additions & 0 deletions docs/verification.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,33 @@
# ターンの失敗が原因を問わず `NATIVE_PROTOCOL_ERROR` になる(2026-11-09)

[Issue #86](https://github.com/supermomonga/paseo-plugin-zcode-provider/issues/86) の対応。ZCode のターンが失敗すると、原因が利用上限・認証・ネットワークのどれであっても、Paseo には `[System Error] ZCode turn failed` と `code: NATIVE_PROTOCOL_ERROR` だけが表示されていた。

## 原因

- `server/session.ts` の `maybeComplete()` は失敗した turnHeader だけを見て、固定の文言と `NATIVE_PROTOCOL_ERROR` を返していた。`server/provider.ts` も文言を `ZCode turn failed` に固定していた。
- ZCode は失敗の内容を V4 の `control.lastError` に入れていたが、プラグインはこれを読んでいなかった。

## 修正

- ターンが失敗したら `control.lastError` の `attribution` を読み、`MODEL_RATE_LIMITED` などのコードとプラグインの固定の英文で伝える。HTTP ステータスとプロバイダーのエラーコードを添え、診断には許可リストに一致した項目だけを加える。プロバイダーの原文は出さない。判断は [ADR 23](adr/0023-ターンの失敗はv4のlasterrorのattributionで分類したコードと固定の文言で伝える.md) に記録した。
- `lastError` が無い失敗と、`runtime`・`tool` の失敗は `NATIVE_TURN_FAILED` とする。
- `test:stdio-runtime` に、ローカルのモデルが 429 を返すシナリオを加えた。`test:upstream` に、Paseo の実際のアダプターでの失敗したターンの確認を加えた。

## ZCode の挙動(3c5b227、管理下ランタイム 3.16.2-paseo.1)

- TurnError では、turnHeader を `failed` にするのと同じフレームで `control.lastError` を設定し、次のターンの開始時に `null` に戻す(`product-projection.ts`)。
- ローカルのモデルから GLM の 429(エラーコード 1310)を返すと、モデルへの要求は 1 回だけで、再試行されなかった。`lastError` は `code: "1310"`、`message` はプロバイダーの原文、`source: "provider"`、`recoverable: true` だった。`attribution` は `reason: "rate_limited"`、`statusCode: 429`、`providerErrorCode: "1310"`、`retryable: false`、`errorPhase: "stream"`、`exceptionKind: "provider_business"` だった。`detail` にはプロバイダー ID・モデル・リクエスト ID が入っていた。
- Desktop の `ChatErrorBanner` は、ローカライズした文言がある code ならその文言を、無ければ `lastError.message` を表示する。

## 検証(Linux x64、Node.js 26.8.1、2026-11-09)

- 追加したテストが修正前に失敗することを確認した。429 の `lastError` があっても、Paseo には `NATIVE_PROTOCOL_ERROR` が届いた。
- `npm run typecheck`、`npm test`(23 ファイル、227 tests)、`npm run build`、`npm run format:check`、`npm run check:zcode-source` が成功した。
- 管理下ランタイム 3.16.2-paseo.1 に対する `npm run test:stdio-runtime` が成功した。追加した 429 のシナリオでは、`MODEL_RATE_LIMITED` が原文を含まずに届き、続くプロンプトが完了した。
- Paseo 0.12.0(`cafe4b01c8522ff39560241c5deb01427dc8dc5b`)に対する `npm run test:upstream` が成功した。ローカルの Paseo のチェックアウトは新しいコミットにあるため、`git clone --shared` で作った別の clone を `cafe4b01` にして、`NODE_PATH` を外して実行した。

未検証:実モデルでの利用上限・認証・ネットワークの失敗。実 daemon と実 UI での表示。Linux x64 以外のプラットフォーム。

# アプリからの Steer が `Duplicate ZCode clientMessageId` で失敗する(2026-10-24)

ZCode の実行中にアプリからメッセージを送ると、`[System Error] Duplicate ZCode clientMessageId` になり、メッセージが届かなかった。
Expand Down
Loading
Loading