cartethyia 2.7.8 → 2.8.0

package/src/protocol/think-split.ts

@@ -152,6 +152,118 @@ function pairedClose(
   return undefined;
 }
 
+/**
+ * Stateful strip of paired thinking tags that preserves source order.
+ *
+ * The reasoning channel (e.g. Chat `reasoning_content`) is one stream where
+ * every byte — tagged or not — is thought. The two-bucket split used by
+ * `ThinkSplitter` (`{ text, reasoning }`) cannot express interleaving, so a
+ * call site that joins `${reasoning}${text}` reorders the stream: untagged
+ * prose that preceded a `<think>` span lands after it. This stripper instead
+ * emits the whole settled content with paired tags removed, in source order,
+ * while keeping `ThinkSplitter`'s stateful guarantees: a tag split across two
+ * deltas is recognized, code spans are left alone, and an unclosed span fails
+ * open at the cap.
+ */
+export class ThinkingTagStripper {
+  #buffer = "";
+  #codeTicks = 0;
+  #codeFenced = false;
+  /** True once an opening tag has been seen and its close has not arrived yet. */
+  #inUnclosedSpan = false;
+  /** The opening tag currently held, restored verbatim on fail-open/flush. */
+  #openMarker = "";
+
+  /** Feeds a chunk; returns settled content with paired tags removed, in order. */
+  push(chunk: string): string {
+    this.#buffer += stripNul(chunk);
+    let out = "";
+    for (;;) {
+      if (this.#inUnclosedSpan) {
+        const closed = this.#findTag(CLOSE_TAGS);
+        if (closed === undefined) break;
+        out += this.#buffer.slice(0, closed.index);
+        this.#buffer = this.#buffer.slice(closed.index + closed.length);
+        this.#codeTicks = closed.codeTicks;
+        this.#codeFenced = closed.codeFenced;
+        this.#inUnclosedSpan = false;
+        this.#openMarker = "";
+        continue;
+      }
+      const opened = this.#findTag(OPEN_TAGS);
+      if (opened === undefined) break;
+      out += this.#buffer.slice(0, opened.index);
+      this.#openMarker = this.#buffer.slice(opened.index, opened.index + opened.length);
+      this.#buffer = this.#buffer.slice(opened.index + opened.length);
+      this.#codeTicks = opened.codeTicks;
+      this.#codeFenced = opened.codeFenced;
+      this.#inUnclosedSpan = true;
+    }
+    if (this.#inUnclosedSpan) {
+      // No close yet: hold the whole span content — including any text after it
+      // — until a later close or `flush()`. Streaming it now would release the
+      // span content before its opening tag on fail-open.
+      if (this.#buffer.length > MAX_THINK_BLOCK_BYTES) {
+        out += this.#openMarker + this.#buffer;
+        this.#buffer = "";
+        this.#inUnclosedSpan = false;
+        this.#openMarker = "";
+      }
+      return out;
+    }
+    const held = danglingTagPrefix(this.#buffer);
+    const settled = held.length > 0 ? this.#buffer.slice(0, -held.length) : this.#buffer;
+    this.#buffer = held;
+    return out + settled;
+  }
+
+  /** Releases content held back for a tag that never completed. */
+  flush(): string {
+    const rest = this.#buffer;
+    this.#buffer = "";
+    this.#codeTicks = 0;
+    this.#codeFenced = false;
+    if (this.#inUnclosedSpan) {
+      // An open tag that never closed is not evidence of reasoning — restore it
+      // byte-for-byte and release the whole tail as-is.
+      const marker = this.#openMarker;
+      this.#inUnclosedSpan = false;
+      this.#openMarker = "";
+      return marker + rest;
+    }
+    return rest;
+  }
+
+  #findTag(tags: readonly string[]): TagMatch | undefined {
+    const buffer = this.#buffer;
+    let ticks = this.#codeTicks;
+    let fenced = this.#codeFenced;
+    for (let i = 0; i < buffer.length; i++) {
+      const char = buffer[i];
+      if (char === "`") {
+        let run = 1;
+        while (buffer[i + run] === "`") run++;
+        if (ticks === 0) {
+          ticks = run;
+          fenced = run >= 3;
+        } else if (run === ticks) {
+          ticks = 0;
+          fenced = false;
+        }
+        i += run - 1;
+        continue;
+      }
+      if (char === "\n" && ticks > 0 && !fenced) ticks = 0;
+      if (char !== "<" || ticks > 0) continue;
+      for (const tag of tags) {
+        if (!buffer.startsWith(tag, i)) continue;
+        return { index: i, length: tag.length, codeTicks: ticks, codeFenced: fenced };
+      }
+    }
+    return undefined;
+  }
+}
+
 /** The longest suffix of `text` that is a proper prefix of any tag. */
 function danglingTagPrefix(text: string): string {
   const tags = [...OPEN_TAGS, ...CLOSE_TAGS];

package/src/protocol/translation/dialect/qwen.ts

@@ -12,77 +12,45 @@
  * rest as text, mirroring the DSML/OMP scanners used for other families.
  */
 import type { InbandScanner, InbandScanResult } from "./inband";
+import { MarkupStreamParser } from "../../markup-stream-parser";
 
 const OPEN_TAG = "<tool_call>";
 const CLOSE_TAG = "</tool_call>";
 
 export class QwenToolCallScanner implements InbandScanner {
-  readonly #allowedNames: ReadonlySet<string>;
-  #pending = "";
-  #sequence = 0;
+  readonly #parser: MarkupStreamParser<InbandScanResult["calls"][number]>;
 
   constructor(allowedNames: ReadonlySet<string>) {
-    this.#allowedNames = allowedNames;
+    this.#parser = new MarkupStreamParser<InbandScanResult["calls"][number]>({
+      openers: [OPEN_TAG],
+      classifyOpener: (_pending, _openIndex, opener) => {
+        if (opener !== OPEN_TAG) return { kind: "literal" };
+        return {
+          kind: "found",
+          closer: CLOSE_TAG,
+          parse: (block) => {
+            const inner = block.slice(OPEN_TAG.length, -CLOSE_TAG.length).trim();
+            const parsed = parseToolCall(inner);
+            if (parsed === undefined) return undefined;
+            if (!allowedNames.has(parsed.name)) {
+              // An undeclared tool is model text, not authority to invoke it.
+              return undefined;
+            }
+            return [parsed];
+          },
+          callId: (call, _index, seq) => ({ ...call, id: `call_qwen_${seq}` }),
+        };
+      },
+      flush: (pending) => (isPossibleOpener(pending) ? "" : pending),
+    });
   }
 
   push(chunk: string): InbandScanResult {
-    this.#pending += chunk;
-    let cursor = 0;
-    let text = "";
-    const calls: Array<InbandScanResult["calls"][number]> = [];
-    for (;;) {
-      const open = this.#pending.indexOf(OPEN_TAG, cursor);
-      if (open < 0) {
-        // Hold a possible pending opener at the tail; settle everything before it.
-        text += this.#pending.slice(cursor, this.#settledEnd(this.#pending.length));
-        cursor = this.#settledEnd(this.#pending.length);
-        break;
-      }
-      text += this.#pending.slice(cursor, open);
-      const bodyStart = open + OPEN_TAG.length;
-      const close = this.#pending.indexOf(CLOSE_TAG, bodyStart);
-      if (close < 0) {
-        // Unterminated block: hold from the opener on and settle what preceded it.
-        cursor = open;
-        break;
-      }
-      const inner = this.#pending.slice(bodyStart, close).trim();
-      const parsed = parseToolCall(inner);
-      if (parsed !== undefined) {
-        if (this.#allowedNames.has(parsed.name)) {
-          calls.push({
-            id: `call_qwen_${this.#sequence++}`,
-            name: parsed.name,
-            arguments: parsed.arguments,
-          });
-        } else {
-          // An undeclared tool is model text, not authority to invoke it.
-          text += this.#pending.slice(open, close + CLOSE_TAG.length);
-        }
-      } else {
-        text += this.#pending.slice(open, close + CLOSE_TAG.length);
-      }
-      cursor = close + CLOSE_TAG.length;
-    }
-    this.#pending = this.#pending.slice(cursor);
-    return { text, calls };
+    return this.#parser.push(chunk);
   }
 
   flush(): InbandScanResult {
-    const pending = this.#pending;
-    this.#pending = "";
-    if (isPossibleOpener(pending)) return { text: "", calls: [] };
-    return { text: pending, calls: [] };
-  }
-
-  #settledEnd(end: number): number {
-    // Keep a trailing fragment that could be the start of an opener.
-    const tail = this.#pending.slice(0, end);
-    const maxPrefix = Math.min(OPEN_TAG.length - 1, tail.length);
-    for (let len = maxPrefix; len > 0; len -= 1) {
-      if (OPEN_TAG.startsWith(tail.slice(-len))) return end - len;
-    }
-    return end;
+    return this.#parser.flush();
   }
 }
 

package/src/protocol/translation/quirks.ts

@@ -49,7 +49,7 @@ interface WireTokenBound {
  * The output limit assumed when the caller states none, for wires that need
  * the field present.
  *
- * PROVEN, not assumed: a 3.16M-char prompt to WorkBuddy/CodeBuddy
+ * PROVEN, not assumed: a 3.16M-char prompt to CodeBuddy
  * (`bansos/deepseek-v4.1-flash`) answered `400 model_param_invalid` whenever
  * `max_tokens` was absent, and answered 200 with the *same* body plus any
  * explicit value — `1`, `16`, `1000`, `8000`, `64000`, `384000` all passed.

package/src/protocol/translation/tool-repair.ts

@@ -91,7 +91,7 @@ export function repairMissingToolResponses(
  * fully answered by matching `tool` results is stripped of its calls (kept when
  * it still carries content), and the dangling results go with it.
  *
- * This is the buddy-family policy (WorkBuddy/CodeBuddy code `11148`): a partial
+ * This is the buddy-family policy (CodeBuddy code `11148`): a partial
  * batch `assistant[c1 c2] + tool[c1]` is a broken sequence the upstream rejects,
  * and a synthesized placeholder cannot stand in for a real execution the model
  * never saw. Contrast `repairMissingToolResponses`, which synthesizes an
@@ -188,7 +188,7 @@ export function repairRequestToolCalls(request: CanonicalRequest): CanonicalRequ
  * True when a `toolResult` part is a `tool`-role turn whose `toolCall` is
  * absent from the whole history, or when results for one batch of calls are
  * not contiguous. Upstreams reject both with `tool_call_sequence_broken`
- * (WorkBuddy/CodeBuddy code `11148`), and a broken history stays broken: the
+ * (CodeBuddy code `11148`), and a broken history stays broken: the
  * client replays it on every later turn, so the whole conversation dies.
  */
 function toolCallIdsIn(message: CanonicalMessage): string[] {

package/src/protocol/upstream/send-claude-messages.ts

@@ -10,6 +10,7 @@ import { applyRouteUserAgent, type ProviderDispatchContext } from "../../provide
 import { abortGatewayError, createUpstreamDeadlineLifecycle } from '../../providers/operations/upstream-deadline';
 import { mapClaudeHttpError } from '../messages-errors';
 import { isRecord } from '../codecs';
+import { upstreamMessageAsIs, MAX_UPSTREAM_ERROR_BYTES } from '../../transport/failure-policy';
 import { parseClaudeSseStream, claudeResponseToEvents } from '../response/messages';
 
 export async function* sendClaudeMessagesRequest(
@@ -67,20 +68,30 @@ export async function* sendClaudeMessagesRequest(
   try {
     json = JSON.parse(body) as unknown;
   } catch {
+    const fallback = "Claude response is not valid JSON (request {requestId}). The upstream came back empty-handed — retry 🌙";
+    const upstreamText = upstreamMessageAsIs(body, "");
     throw new GatewayError(
       "platform_unavailable",
       502,
-      "Claude response is not valid JSON (request {requestId}). The upstream came back empty-handed — retry 🌙",
-      {},
+      upstreamText.message || fallback,
+      {
+        raw: body.slice(0, MAX_UPSTREAM_ERROR_BYTES),
+        ...(upstreamText.hadUpstreamText ? { upstreamMessageAsIs: true } : {}),
+      },
       "upstream",
     );
   }
   if (!isRecord(json)) {
+    const fallback = "Claude response must be an object (request {requestId}). The upstream came back empty-handed — retry 🌙";
+    const upstreamText = upstreamMessageAsIs(body, "");
     throw new GatewayError(
       "platform_unavailable",
       502,
-      "Claude response must be an object (request {requestId}). The upstream came back empty-handed — retry 🌙",
-      {},
+      upstreamText.message || fallback,
+      {
+        raw: body.slice(0, MAX_UPSTREAM_ERROR_BYTES),
+        ...(upstreamText.hadUpstreamText ? { upstreamMessageAsIs: true } : {}),
+      },
       "upstream",
     );
   }

package/src/protocol/upstream-parsing.ts

@@ -71,7 +71,7 @@ export function parseUpstreamBackoff(headers: {
  *
  *   - **Relative** — "quota will reset in 3 hours", "try again in 30s".
  *   - **Absolute** — "your usage will reset at 2026-09-24 02:12:51 UTC+8"
- *     (WorkBuddy/CodeBuddy `6004`). An absolute stamp is *not* a duration, and
+ *     (CodeBuddy `6004`). An absolute stamp is *not* a duration, and
  *     the relative-only pattern silently missed it, so the account fell back to
  *     the generic 15-minute default while the provider had actually parked it
  *     for the rest of the window — the account kept re-entering rotation and

package/src/providers/adapters/compatible-adapter.ts

@@ -6,9 +6,9 @@ import {
   isContextLengthFailure,
   throwIfHtmlResponse,
   mapUpstreamHttpError,
-  extractUpstreamMessage,
   extractHtmlTitle,
   upstreamErrorIdentifier,
+  upstreamMessageAsIs,
 } from "../../transport/failure-policy";
 import { applyRouteUserAgent, type ProviderDispatchTarget, type ProviderId, type ProviderDispatchContext } from "../provider-contracts";
 import { BaseProviderAdapter } from "./base-adapter";
@@ -17,6 +17,7 @@ import { resolveDialect } from "../../protocol/translation/dialect/resolver";
 import { resolveThinkingForModel } from "../../protocol/translation/dialect/thinking-ladder";
 import type { DialectPolicy } from "../../protocol/translation/dialect/types";
 import { postUpstreamJson } from "../../protocol/upstream/post-json";
+import { gzipSync } from "node:zlib";
 import { GATEWAY_USER_AGENT } from "../operations/gateway-user-agent";
 import { resolvePromptCacheKey } from "../operations/session-resolution";
 import {
@@ -28,6 +29,24 @@ import {
 } from "../../protocol/codecs";
 const TEXT_DECODER = new TextDecoder("utf-8", { fatal: false });
 
+/**
+ * Whether an upstream error body is the channel-check rejection the CodeBuddy
+ * console fallback recovers from. Ported from the donor gateway
+ * (`codebuddy2api/upstream_compat.is_channel_check_error`): it requires both
+ * a channel-check business code (`11128` / `11-128`) and one of the
+ * explanatory texts. A bare code match swept unrelated failures into a retry.
+ */
+export function isBuddyChannelCheckError(raw: string): boolean {
+  if (!/code["']?\s*:\s*["']?(?:11128|11-128)/i.test(raw)) return false;
+  const lower = raw.toLowerCase();
+  return (
+    lower.includes("渠道校验") || // 渠道校验
+    lower.includes("channel verification") ||
+    lower.includes("official client") ||
+    lower.includes("illegal api invocation from an unapproved channel")
+  );
+}
+
 /**
  * Provider ids that understand the OpenAI-style `service_tier` control. Only
  * these upstreams accept the field; every other OpenAI-compatible provider
@@ -111,8 +130,21 @@ export interface OpenAICompatibleAdapterConfig {
    * stamps `Content-Encoding: zstd` — the Grok Build CLI does this via its
    * sampler (`request_compression.rs`), and the proxy accepts it (verified
    * live 2026-11-02). Falls back to plain JSON if the runtime lacks zstd.
+   * `"gzip"` compresses with `gzipSync` and stamps `Content-Encoding: gzip`
+   * — the CodeBuddy CLI contract (donor `codebuddy2api`): the CLI profiles
+   * always compress; the CN desktop profile compresses requests >= 1024 B.
+   * The caller must also send `Accept-Encoding: identity` (the compressed
+   * body and the uncompressed response are independent choices).
+   */
+  readonly request_compression?: "json" | "zstd" | "gzip";
+  /**
+   * One retry against this path when the primary chat endpoint answers a
+   * channel-check 400 (`11128` / `11-128`). Matches the donor gateway's
+   * `/console/chat/completions` fallback for the international profile: the
+   * primary `v2` endpoint rejects requests that do not carry the channel
+   * marker, and a single console retry is the reference's recovery.
    */
-  readonly request_compression?: "json" | "zstd";
+  readonly channel_fallback_path?: string;
   /**
    * Stamps `user-agent: Cartethyia/<version>` on every dispatch. Explicit
    * opt-in per provider spec — never a default — so first-party cloaking
@@ -216,6 +248,13 @@ export class OpenAICompatibleAdapter extends BaseProviderAdapter {
     // here — alongside the other request headers — so auth/proxy layers see the
     // final shape before the transport runs.
     if (this.config.request_compression === "zstd") headers["content-encoding"] = "zstd";
+    else if (this.config.request_compression === "gzip") {
+      headers["content-encoding"] = "gzip";
+      // The compressed request and the response encoding are independent; the
+      // reference requests the identity response encoding so the stream arrives
+      // uncompressed (matching `Accept-Encoding: identity` in the donor).
+      headers["accept-encoding"] = "identity";
+    }
     Object.assign(headers, filterProviderCustomHeaders(context.credential.custom_headers));
     applyRouteUserAgent(headers, context.credential, context.user_agent);
     return headers;
@@ -330,18 +369,38 @@ export class OpenAICompatibleAdapter extends BaseProviderAdapter {
       return u.toString();
     })();
     const outboundFetch = context.outbound_fetch ?? this.config.fetch ?? globalThis.fetch;
-    const upstream = await postUpstreamJson(
-      fetchUrl,
-      headers,
-      payload as Record<string, unknown>,
-      context,
-      outboundFetch,
-      // zstd body encoding: matches the Grok Build CLI's
-      // `request_compression` (zstd with a JSON fallback when unavailable).
+    const bodyEncoder =
       this.config.request_compression === "zstd" && typeof Bun?.zstdCompressSync === "function"
-        ? (p) => Bun.zstdCompressSync(Buffer.from(JSON.stringify(p))) as Uint8Array<ArrayBuffer>
-        : undefined,
-    );
+        ? (p: Record<string, unknown>) => Bun.zstdCompressSync(Buffer.from(JSON.stringify(p))) as Uint8Array<ArrayBuffer>
+        : this.config.request_compression === "gzip"
+          ? (p: Record<string, unknown>) => gzipSync(Buffer.from(JSON.stringify(p)), { level: 6 })
+          : undefined;
+    const channelFallback =
+      this.config.channel_fallback_path !== undefined &&
+      endpointPath !== this.config.channel_fallback_path
+        ? joinUrl(this.config.resolveBaseUrl?.(context) ?? this.config.base_url, this.config.channel_fallback_path)
+        : undefined;
+    const upstream = await postUpstreamJson(fetchUrl, headers, payload as Record<string, unknown>, context, outboundFetch, bodyEncoder);
+    if (channelFallback !== undefined && upstream.res.status === 400) {
+      // Read the body only for a 400 that could still be retried. The channel
+      // check is the one refusal the console endpoint recovers from; a rejected
+      // body is consumed here so the fallback attempt carries a fresh stream.
+      const raw = await upstream.res.text().catch(() => "");
+      upstream.release();
+      if (isBuddyChannelCheckError(raw)) {
+        const retry = await postUpstreamJson(channelFallback, headers, payload as Record<string, unknown>, context, outboundFetch, bodyEncoder);
+        retry.release();
+        return retry.res;
+      }
+      // Not a channel check — reconstruct the 400 response so downstream error
+      // classification still sees the upstream's body. A `Response` body can be
+      // consumed once, so rebuild it from the captured text.
+      return new Response(raw, {
+        status: 400,
+        statusText: upstream.res.statusText,
+        headers: { "content-type": "application/json" },
+      });
+    }
     upstream.release();
     return upstream.res;
   }
@@ -439,11 +498,12 @@ export class OpenAICompatibleAdapter extends BaseProviderAdapter {
         }
         json = parsed as Record<string, unknown>;
       } catch {
-        const summary = extractHtmlTitle(raw) || raw.trim() || `HTTP ${res.status}`;
+        const fallback = `Upstream returned a non-JSON response: ${extractHtmlTitle(raw) || raw.trim() || `HTTP ${res.status}`} (request {requestId}). The connection ghosted us — come back in a moment 👻`;
+        const upstreamText = upstreamMessageAsIs(raw, "");
         throw new GatewayError(
           "transport_unavailable",
           502,
-          `Upstream returned a non-JSON response: ${summary} (request {requestId}). The connection ghosted us — come back in a moment 👻`.slice(0, 320),
+          `${upstreamText.message || fallback}`.slice(0, 500),
           { upstreamStatus: res.status, contentType },
           "upstream",
         );
@@ -485,15 +545,16 @@ export class OpenAICompatibleAdapter extends BaseProviderAdapter {
         const classification = isContextLengthFailure(json)
           ? { code: "context_length_exceeded" as const, status: 413, origin: "upstream" as const, credentialEvidence: false, rateLimitScope: undefined }
           : classifyUpstreamError(providerStatus, identifier);
-        const message = extractUpstreamMessage(json) || "Upstream reported an error";
+        const upstreamText = upstreamMessageAsIs(json, "");
         throw new GatewayError(
           classification.code,
           classification.status,
-          message,
+          upstreamText.message || "Upstream reported an error",
           {
             providerId: this.provider_id,
             ...(providerStatus === undefined ? {} : { providerStatus }),
             ...(identifier === undefined ? {} : { providerCode: identifier }),
+            ...(upstreamText.hadUpstreamText ? { upstreamMessageAsIs: true } : {}),
             ...(classification.credentialEvidence ? { credentialEvidence: true } : {}),
             ...(classification.rateLimitScope
               ? { rateLimitScope: classification.rateLimitScope }

package/src/providers/authentication/oauth-client.ts

@@ -23,7 +23,7 @@ import type { OAuthTokenRefreshResult, OAuthTokenRefresher } from "./oauth-refre
 export type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 
 /** Normalized token shape returned by provider token endpoints. */
-interface NormalizedTokenResponse {
+export interface NormalizedTokenResponse {
   readonly access: string;
   readonly refresh: string;
   readonly expiresAt: Date;

package/src/providers/authentication/oauth-device-flow.ts

@@ -8,8 +8,9 @@ import type {
   OAuthDeviceFlowContext,
   OAuthDevicePollResult,
   OAuthDeviceStartResult,
+  OAuthExchangeResult,
 } from "./oauth-flow-store";
-import { OAuthClient } from "./oauth-client";
+import { OAuthClient, type NormalizedTokenResponse } from "./oauth-client";
 
 /** Configuration for standard device-code start and poll requests. */
 export interface DeviceFlowConfig {
@@ -67,6 +68,58 @@ export abstract class OAuthDeviceFlow extends OAuthClient {
     return new URLSearchParams(params);
   }
 
+  /**
+   * Optional verdict computed from the parsed token body before the status
+   * code is considered. Defaults to undefined (continue with standard
+   * handling). A provider whose authoritative endpoint states the poll state
+   * in the body on any status can return a backoff verdict here — e.g. Grok,
+   * which votes on `error` before the HTTP status.
+   */
+  protected preVerdict?(_payload: unknown): OAuthDevicePollResult | undefined;
+
+  /**
+   * Post-success hook for the standard device-token poll.
+   *
+   * Receives the raw token response payload and the normalized parsed token.
+   * Returns the exchange result to complete with, or a verdict (typically
+   * `failed`) instead. The default reproduces the generic behavior exactly.
+   * Errors thrown by a hook are converted to a `failed` verdict by
+   * `pollGenericDeviceAuth`, keeping the poll contract (verdicts, never
+   * throws).
+   */
+  protected afterDeviceTokenExchange?(
+    _payload: unknown,
+    _normalized: NormalizedTokenResponse,
+  ): OAuthExchangeResult | OAuthDevicePollResult | Promise<OAuthExchangeResult | OAuthDevicePollResult>;
+
+  /**
+   * Failure reason for a non-JSON token body. Defaults to the generic
+   * phrasing; providers whose wire carries a distinct message override it.
+   */
+  protected unparsablePollReason(status: number): string {
+    return `device polling failed (${status})`;
+  }
+
+  /**
+   * Failure reason for a non-OK token response. The default preserves the
+   * generic behavior: the response's `error` field names the reason on the
+   * RFC 8628 400/428 statuses, and every other non-OK status gets the generic
+   * phrasing (the body is not trusted there).
+   */
+  protected pollFailureReason(
+    status: number,
+    errorKey: string | undefined,
+    _errorDescription: string | undefined,
+  ): string {
+    if (status === 400 || status === 428) return errorKey || `device polling failed (${status})`;
+    return `device polling failed (${status})`;
+  }
+
+  /** Failure reason when a token response omits `access_token`. */
+  protected missingTokenReason(_errorKey: string | undefined, _errorDescription: string | undefined): string {
+    return `${this.providerLabel} token response omitted access_token`;
+  }
+
   /** Standard device-token poll. Returns pending while authorization is incomplete. */
   protected async pollGenericDeviceAuth(
     deviceAuthId: string,
@@ -88,20 +141,57 @@ export abstract class OAuthDeviceFlow extends OAuthClient {
     } catch {
       payload = undefined;
     }
+    // A body that is not JSON is a failed poll regardless of status: verdicts
+    // must never throw, and the reason below lets providers keep their own
+    // phrasing (e.g. Grok's "returned invalid JSON").
+    if (payload === undefined) {
+      return { status: "failed", reason: this.unparsablePollReason(response.status) };
+    }
     const root = record(payload) ?? {};
+    if (this.preVerdict) {
+      const verdict = this.preVerdict(payload);
+      if (verdict !== undefined) return verdict;
+    }
+    const errorKey = typeof root.error === "string" ? root.error : undefined;
+    const errorDescription = typeof root.error_description === "string" ? root.error_description : undefined;
     if (response.status === 400 || response.status === 428) {
-      const err = typeof root.error === "string" ? root.error : "";
-      const verdict = devicePollBackoff(err, root.interval);
+      const verdict = devicePollBackoff(errorKey, root.interval);
       if (verdict !== undefined) return verdict;
-      return { status: "failed", reason: err || `device polling failed (${response.status})` };
+      return {
+        status: "failed",
+        reason: this.pollFailureReason(response.status, errorKey, errorDescription),
+      };
     }
-    if (!response.ok || payload === undefined) {
-      return { status: "failed", reason: `device polling failed (${response.status})` };
+    if (!response.ok) {
+      return { status: "failed", reason: this.pollFailureReason(response.status, errorKey, errorDescription) };
     }
     if (typeof root.access_token !== "string" || !root.access_token) {
-      return { status: "failed", reason: `${this.providerLabel} token response omitted access_token` };
+      return {
+        status: "failed",
+        reason: this.missingTokenReason(errorKey, errorDescription),
+      };
+    }
+    let normalized: NormalizedTokenResponse;
+    try {
+      normalized = this.parseTokenResponse(payload);
+    } catch (error) {
+      return {
+        status: "failed",
+        reason: error instanceof Error ? error.message : `${this.providerLabel} token response omitted access_token`,
+      };
+    }
+    if (this.afterDeviceTokenExchange) {
+      try {
+        const hooked = await this.afterDeviceTokenExchange(payload, normalized);
+        if ("status" in hooked) return hooked;
+        return { status: "complete", result: hooked };
+      } catch (error) {
+        return {
+          status: "failed",
+          reason: error instanceof Error ? error.message : `${this.providerLabel} authentication failed`,
+        };
+      }
     }
-    const normalized = this.parseTokenResponse(payload);
     return { status: "complete", result: this.toExchangeResult(normalized) };
   }
 }