Repository navigation
fix: report why a ZCode turn failed - #91
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #86.
Problem
Every failed ZCode turn reached Paseo as:
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_ERRORsuggested a plugin bug.Cause
ZCodeSession.maybeComplete()saw only the failedturnHeaderand emitted a fixed message withNATIVE_PROTOCOL_ERROR.provider.tsreplaced the message with another constant.control.lastError, which the plugin never read. At3c5b227,product-projection.tssets it in the same frame that fails the turn header and clears it when the next turn starts. Desktop'sChatErrorBannershows it.turn.failedevent. The plugin uses only V4 conversation state (ADR 13);lastErrorcarries the same error detail officially.On the managed 3.16.2-paseo.1 runtime, a local model returning GLM's 429 with code
1310produced thislastError:code: "1310", the provider's Chinese quota text asmessage,recoverable: true, andattributionwithsource: "provider",reason: "rate_limited",statusCode: 429,providerErrorCode: "1310",retryable: false.lastError.codeis the provider's own code, so the plugin classifies byattributioninstead.Change
server/turn-failure.tsclassifieslastErrorbyattribution.source(orlastError.source) andattribution.reason(ZCode'sModelFailureReason):MODEL_RATE_LIMITED,MODEL_AUTH_FAILED,MODEL_CONTEXT_EXCEEDED,MODEL_NETWORK_ERROR,MODEL_PROVIDER_ERROR, orMODEL_REQUEST_FAILEDfor any other provider reason;lastError:NATIVE_TURN_FAILED. Turn failures no longer useNATIVE_PROTOCOL_ERROR.formatDiagnosticgainsstage: "turn"and afailureobject with only allowlistedsource,reason,errorPhase,exceptionKind, a 100–599statusCode, a reportableproviderErrorCodeandretryable.providerId/modelIdare excluded because they can contain user-chosen names.message,detailandunderlyingErrorMessageare 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.docs/development.mdanddocs/verification.mdare updated.test:stdio-runtimegains a scenario where the local model returns 429/1310: the turn must fail withMODEL_RATE_LIMITED, without the provider's text, and the next prompt must complete.test:upstreamsends a classified failure through Paseo's real adapter.Verification (Linux x64, Node.js 26.8.1)
lastError, Paseo still receivedNATIVE_PROTOCOL_ERROR.npm run typecheck,npm test(23 files, 227 tests),npm run build,npm run format:check,npm run check:zcode-sourceandgit diff --checkpassed.npm run test:stdio-runtimeagainst the managed 3.16.2-paseo.1 runtime passed, including the new quota failure and the restart after it.npm run test:upstreamagainst Paseo 0.12.0 (cafe4b01c8522ff39560241c5deb01427dc8dc5b) passed, including the newturnFailurecheck. The local Paseo checkout is on a newer commit, so it ran on agit clone --sharedatcafe4b01, withoutNODE_PATH.adrs doctorreports no new diagnostics.Not verified