Skip to content

fix: report why a ZCode turn failed - #91

Merged
supermomonga merged 1 commit into
mainfrom
fix/turn-failure-error-detail
Nov 9, 2026
Merged

supermomonga merged 1 commit into
mainfrom
fix/turn-failure-error-detail

Conversation

@supermomonga

Copy link
Copy Markdown
Owner

Fixes #86.

Problem

Every failed ZCode turn reached Paseo as:

[System Error] ZCode turn failed
code: NATIVE_PROTOCOL_ERROR

A provider quota (HTTP 429), a sign-in failure and a network error looked the same to the user and to an orchestrating agent, and NATIVE_PROTOCOL_ERROR suggested a plugin bug.

Cause

  • ZCodeSession.maybeComplete() saw only the failed turnHeader and emitted a fixed message with NATIVE_PROTOCOL_ERROR. provider.ts replaced the message with another constant.
  • ZCode already records the failure in the V4 control.lastError, which the plugin never read. At 3c5b227, product-projection.ts sets it in the same frame that fails the turn header and clears it when the next turn starts. Desktop's ChatErrorBanner shows it.
  • The issue suggests the legacy turn.failed event. The plugin uses only V4 conversation state (ADR 13); lastError carries the same error detail officially.

On the managed 3.16.2-paseo.1 runtime, a local model returning GLM's 429 with code 1310 produced this lastError: code: "1310", the provider's Chinese quota text as message, recoverable: true, and attribution with source: "provider", reason: "rate_limited", statusCode: 429, providerErrorCode: "1310", retryable: false. lastError.code is the provider's own code, so the plugin classifies by attribution instead.

Change

  • Classification. On a failed turn, server/turn-failure.ts classifies lastError by attribution.source (or lastError.source) and attribution.reason (ZCode's ModelFailureReason):
    • provider/network failures: MODEL_RATE_LIMITED, MODEL_AUTH_FAILED, MODEL_CONTEXT_EXCEEDED, MODEL_NETWORK_ERROR, MODEL_PROVIDER_ERROR, or MODEL_REQUEST_FAILED for any other provider reason;
    • runtime/tool failures, or no lastError: NATIVE_TURN_FAILED. Turn failures no longer use NATIVE_PROTOCOL_ERROR.
  • Message. The plugin's own English text with the HTTP status and a numeric or word provider code, plus advice. For a quota it points to Paseo 0.11's Usage screen for Coding Plan reset times. Example:

    The model provider's usage or rate limit was reached (HTTP 429, provider code 1310). Wait for it to reset or switch models. For a ZCode Coding Plan, Paseo 0.11 and later show the reset times on the Usage screen.

  • Diagnostic. formatDiagnostic gains stage: "turn" and a failure object with only allowlisted source, reason, errorPhase, exceptionKind, a 100–599 statusCode, a reportable providerErrorCode and retryable. providerId/modelId are excluded because they can contain user-chosen names.
  • No native text. ZCode's message, detail and underlyingErrorMessage are never shown. Provider error text can contain request content or key fragments, and Paseo stores turn failures in the timeline and passes them to agents (ADR 7). The trade-off is that the provider's reset time is not shown.
  • ADR 23 records the decision and amends ADR 7. README, docs/development.md and docs/verification.md are updated.
  • Runtime checks. test:stdio-runtime gains a scenario where the local model returns 429/1310: the turn must fail with MODEL_RATE_LIMITED, without the provider's text, and the next prompt must complete. test:upstream sends a classified failure through Paseo's real adapter.

Verification (Linux x64, Node.js 26.8.1)

  • Regression tests. The new provider tests failed before the fix: with a 429 lastError, Paseo still received NATIVE_PROTOCOL_ERROR.
  • Static checks. npm run typecheck, npm test (23 files, 227 tests), npm run build, npm run format:check, npm run check:zcode-source and git diff --check passed.
  • Runtime. npm run test:stdio-runtime against the managed 3.16.2-paseo.1 runtime passed, including the new quota failure and the restart after it.
  • Upstream. npm run test:upstream against Paseo 0.12.0 (cafe4b01c8522ff39560241c5deb01427dc8dc5b) passed, including the new turnFailure check. The local Paseo checkout is on a newer commit, so it ran on a git clone --shared at cafe4b01, without NODE_PATH.
  • adrs doctor reports no new diagnostics.

Not verified

  • Real quota, sign-in or network failures with a real model.
  • The message in the Paseo app and daemon.
  • Platforms other than Linux x64.

A failed ZCode turn always reached Paseo as "ZCode turn failed" with
NATIVE_PROTOCOL_ERROR, so a provider quota (HTTP 429), sign-in or
network failure could not be told apart, and the code suggested a
protocol bug.

ZCode records the failure in the V4 control.lastError of the frame that
fails the turn. Classify it by its attribution source and reason into
MODEL_RATE_LIMITED, MODEL_AUTH_FAILED, MODEL_CONTEXT_EXCEEDED,
MODEL_NETWORK_ERROR, MODEL_PROVIDER_ERROR or MODEL_REQUEST_FAILED, and
NATIVE_TURN_FAILED otherwise. The message is the plugin's own text with
the HTTP status and the provider's error code; the diagnostic adds only
allowlisted attribution fields. ZCode's message and detail are never
shown, as ADR 7 requires. Record the decision in ADR 23.

Add a provider quota failure to test:stdio-runtime and a failed turn to
test:upstream.
@supermomonga
supermomonga merged commit aa2ff89 into main Nov 9, 2026
14 checks passed
@supermomonga
supermomonga deleted the fix/turn-failure-error-detail branch November 9, 2026 03:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

ZCode turn failures mask the real cause (e.g. weekly quota 429) as generic NATIVE_PROTOCOL_ERROR

1 participant