Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

47.7 KB
Raw Blame
/**
 * probe-live — send real 1-token chat requests through the running proxy
 * to validate that each link in a model's fallback chain actually works.
 *
 * The probe goes through the same proxy that serves real traffic, so it
 * exercises every layer: API key resolution (env/.env/config.json),
 * routing rules, transport classes, adapter format, and stream parser.
 *
 * Each link is pinned to a single provider by passing its `provider@model`
 * spec as the request body. The runtime router sees `isExplicitProvider`
 * and skips fallback — so a failure here is a real failure for that link,
 * not a silent failover to something else.
 */

import { extractUpstreamStatus, sseDataPayload } from "../handlers/shared/anthropic-error.js";
import {
  type HopFailureReason,
  UNHANDLED_ERROR_HEADER,
  decideHopFailure,
} from "../handlers/shared/hop-decision.js";
import {
  hasActionableLink,
  hasModelUnsupportedWording,
} from "../handlers/shared/model-unsupported.js";
import { hasPlanLimitWording } from "../handlers/shared/quota-exhaustion.js";

export type ProbeState =
  | "live"
  | "key-missing"
  | "auth-failed"
  | "model-not-found"
  | "rate-limited"
  | "out-of-credit"
  /**
   * A flat-rate allowance is spent for this cycle. Distinct from
   * `out-of-credit`: the account CAN be billed, the plan window simply has not
   * reset, so the remedy is to wait or upgrade rather than to top up a balance.
   */
  | "plan-limit"
  | "server-error"
  | "timeout"
  | "network-error"
  | "error";

export interface ProbeResult {
  state: ProbeState;
  /** Total wall-clock from request start to finished reading the response. */
  latencyMs: number;
  httpStatus?: number;
  errorMessage?: string;
  /** Hint shown after the error message (e.g. "run: claudish login gemini"). */
  actionHint?: string;
  /**
   * Granular timing breakdown, present on successful ("live") probes. The three
   * stages are sequential and sum to ~latencyMs:
   *   network   = ttfbMs                 (connect + proxy + provider accept)
   *   server    = ttftMs - ttfbMs        (provider thinking before first token)
   *   streaming = latencyMs - ttftMs     (token generation)
   */
  timing?: ProbeTiming;
  /**
   * The credential that signed THIS probe request, when the provider has
   * several login sources (muse@): `Muse Code borrowed copy · <tier>`. Read off
   * the response's `x-claudish-signed-with`, so it is per request.
   */
  signedWith?: string;
  /**
   * What a routing chain would do after this hop's answer, by the runtime's rule
   * (`decideHopFailure`). Absent on "live", and on a result the probe never sent
   * (`key-missing`): a caller that walks a chain treats absent as "stop".
   */
  chainAction?: "advance" | "stop";
  /** Why: a `HopFailureReason`, or a probe-only cause. */
  chainReason?: ProbeChainReason;
}

/** Why a probed hop advances or stops the chain. */
export type ProbeChainReason =
  | HopFailureReason
  /** The stream failed after a 200, which the runtime already returned. */
  | "after-200"
  /** The probe's own deadline; the runtime has none per hop, so it would wait. */
  | "probe-timeout"
  /** The probe could not reach the proxy at all. */
  | "proxy-unreachable";

/**
 * Minimum streaming window (ms) used when deriving tokens/sec. A response whose
 * whole (token-capped) body lands in ~one chunk has TTFT ≈ total, so the raw
 * streaming window collapses toward zero and `tokens / streamMs` explodes into a
 * nonsense rate (e.g. 49000 t/s). Flooring the window to this constant bounds the
 * rate to a defensible "tokens over a floored window" value. BOTH the displayed
 * value (here) and the bar SCALE (computeBarScales / probe-tui-app.tsx) floor by
 * this same constant so the number you read and the bar you see derive from one
 * window and never disagree. Lives here (the canonical timing module) so the TUI
 * theme can reference it without the network path depending on @opentui/core.
 */
export const STREAM_MS_FLOOR = 50;

export interface ProbeTiming {
  /** Time to response headers (ms from request start). */
  ttfbMs: number;
  /** Time to first content token (ms from request start). */
  ttftMs: number;
  /** Time reading the full (capped) response (ms from request start) = total. */
  totalMs: number;
  /** Output tokens observed in the streamed response. */
  tokens: number;
  /** Streaming throughput = tokens / (streaming seconds). 0 if unmeasurable. */
  tokensPerSec: number;
}

/**
 * Providers that authenticate via OAuth rather than a static env-var key.
 * Their static credential check is unreliable (no env var to test), so the
 * probe must treat the live request as the source of truth: if it returns a
 * token-related failure, we surface a login hint instead of masking the link
 * as "skipped".
 */
const OAUTH_PROVIDERS = new Set(["vertex", "antigravity", "devin", "meta-muse-code"]);
// Ask for a short paragraph so we can sample streaming throughput (tokens/sec).
// Capped to keep probes quick while leaving room for reasoning models that
// spend hidden reasoning tokens BEFORE any visible text: at 64 tokens, models
// like gpt-5-nano burned the whole budget on reasoning → HTTP 200 with zero
// visible content → false FAIL. 512 leaves visible output for every model
// verified while keeping the probe under ~1-3s of generation.
const PROBE_PROMPT = "Count from one to twenty in words, one per line.";
export const PROBE_MAX_TOKENS = 512;

export interface ProbeLinkInput {
  provider: string;
  modelSpec: string;
  hasCredentials: boolean;
  credentialHint?: string;
}

/**
 * Providers whose API validates `output_config.effort` against an enum that has
 * no "minimal". Anthropic's is `low | medium | high | xhigh | max`, and the
 * native passthrough reaches it directly — no adapter clamp in between — so an
 * unmapped "minimal" is a 400 before the request is ever evaluated.
 *
 * "low" rather than omitting the field: the point of setting effort at all is to
 * stop a reasoning model spending the whole probe cap on hidden reasoning and
 * returning 200 with zero visible text. "low" preserves that intent and is
 * accepted (both verified against the live API).
 *
 * `google` is here for the Gemini 3 thinking levels. Measured 2026-09-19 on the
 * direct API: gemini-3.8-flash answers `400 "Thinking level MINIMAL is not
 * supported for this model"`, while "low" and "high" return 200; gemini-2.5-flash
 * accepts all of them, since 2.5 takes a numeric budget instead. The probe pick
 * for google is a Gemini 3 model, so every Gemini probe failed on its effort
 * field. (Antigravity serves both families and needs no field at all — see
 * EFFORT_OMITTED below.)
 *
 * `qwen-payg` validates the enum the same way Anthropic does, and says so:
 * `400 InvalidParameter "Invalid value 'minimal' for output_config.effort.
 * Supported values are: low, medium, high, xhigh, max."` (measured 2026-09-20 on
 * dashscope-intl with qwen3.8-max-0902). Its sibling products do not: the Token
 * Plan host accepts "minimal" on the same round of measurements, so this is one
 * product's host, not a vendor-wide rule.
 *
 * The three Z.ai products (`glm`, `z-ai`, `glm-coding` — one endpoint, three key
 * silos) are here for a DIFFERENT reason, and it is worth stating because the
 * remedy looks the same while the cause is not. Z.ai accepts the word "minimal"
 * perfectly well; what it refuses is the REQUEST that word produces. The GLM
 * dialect maps "minimal" to `thinking: {type: "disabled"}`, and GLM-5.3 cannot
 * be told to stop thinking. Measured 2026-09-22 against api.z.ai with glm-5.3:
 *
 *   {"thinking":{"type":"disabled"}}                    -> 400 code 1210
 *     "This model always engages in thinking and cannot be disabled;
 *      please use low, high, or max"
 *   {"thinking":{"type":"enabled"},"reasoning_effort":"low"} -> 200
 *
 * Only `glm` failed Test All, because its probe pick discovers `glm-5.3` while
 * `z-ai` and `glm-coding` pick the Flash variants, which still accept the
 * off-switch. All three are listed anyway: the constraint belongs to the GLM
 * family on this endpoint, not to whichever model discovery happens to rank
 * first today, and pinning only the one that broke would make the next pick a
 * new bug.
 */
const MINIMAL_EFFORT_UNSUPPORTED = new Set([
  "native-anthropic",
  "anthropic",
  "google",
  "qwen-payg",
  "glm",
  "z-ai",
  "glm-coding",
]);

/**
 * Providers where NO effort value is valid for every model they serve, so the
 * probe sends none and lets each model use its default.
 *
 * Antigravity serves Gemini 2.5, Gemini 3 and Claude behind one request shape,
 * and the probe knows only the provider, never the model family. Measured
 * 2026-09-19 with the 512-token probe cap:
 *   - "minimal" → `thinkingBudget: 0` on Gemini 2.5, which Antigravity rejects:
 *     `400 INVALID_ARGUMENT` on gemini-2.5-flash and gemini-2.5-flash-lite.
 *   - "low" → a 1024-token budget, which Claude rejects because it is not below
 *     the cap: "`max_tokens` must be greater than `thinking.budget_tokens`".
 *   - no field → 200 on all of them.
 * Claude Code never sends "minimal" and sends a far larger max_tokens, so user
 * sessions reach neither failure through this path.
 */
const EFFORT_OMITTED = new Set(["antigravity"]);

function effortForProvider(provider: string): string | undefined {
  if (EFFORT_OMITTED.has(provider)) return undefined;
  return MINIMAL_EFFORT_UNSUPPORTED.has(provider) ? "low" : "minimal";
}

export async function probeLink(
  proxyUrl: string,
  link: ProbeLinkInput,
  timeoutMs: number
): Promise<ProbeResult> {
  const isOAuth = OAUTH_PROVIDERS.has(link.provider);

  if (!link.hasCredentials && !isOAuth) {
    return {
      state: "key-missing",
      latencyMs: 0,
      errorMessage: link.credentialHint,
    };
  }

  const startedAt = Date.now();
  const probeEffort = effortForProvider(link.provider);
  let response: Response;

  try {
    response = await fetch(`${proxyUrl}/v1/messages`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        // A probe must FAIL FAST. Every probe POSTs /v1/messages through the
        // proxy, so it enters the same handler as a real turn — and a real
        // turn now holds an unreachable provider open for the whole tier-1
        // deadline. Without this header, probing an unreachable link would
        // burn the probe's own timeout and then report `timeout` (the probe's
        // abort fires first) instead of `network-error`, breaking `--probe`
        // and the config TUI's Test All for exactly the failure they exist to
        // diagnose — and multiplying a Test All run by that timeout per dead
        // link.
        "x-claudish-no-recovery": "1",
      },
      body: JSON.stringify({
        model: link.modelSpec,
        // Include a system field so Codex-family providers (which require
        // `instructions` derived from system) accept the request. Other
        // providers tolerate the extra field.
        system: "You are a helpful assistant.",
        messages: [{ role: "user", content: PROBE_PROMPT }],
        max_tokens: PROBE_MAX_TOKENS,
        // Probe-only: force MINIMAL reasoning. A probe just needs a few visible
        // tokens to prove the link is alive — but a reasoning model (e.g.
        // gpt-5-nano) left to its default budget spends the WHOLE probe cap on
        // hidden reasoning before any visible text (HTTP 200, finish=length, 0
        // chars — intermittent FAIL, ~60% in testing). "minimal" zeroes the
        // reasoning budget → deterministic visible output in ~1s (10/10 vs the
        // default's 2/5). The v7.11.0 effort mapping clamps "minimal" per model
        // family. Real user sessions are unaffected — Claude Code builds its own
        // output_config from the user's effort setting; this field is set ONLY
        // here, on the probe request.
        //
        // "non-reasoning/non-OpenAI providers ignore output_config, so this is
        // safe for every probe target" — that used to be written here and is
        // FALSE. The native-anthropic link reaches api.anthropic.com directly,
        // bypassing the effort clamp, and that API validates the enum:
        // `output_config.effort: Input should be 'low', 'medium', 'high',
        // 'xhigh' or 'max'`. Measured 2026-08-18 — "minimal" 400s, "low" and
        // omitting the field both return 200. So EVERY native-anthropic probe
        // failed on the payload before the model id was even considered, which
        // is why that link could never report `live`.
        ...(probeEffort ? { output_config: { effort: probeEffort } } : {}),
        stream: true,
      }),
      signal: AbortSignal.timeout(timeoutMs),
    });
  } catch (e: any) {
    const latencyMs = Date.now() - startedAt;
    const name = e?.name || "";
    const msg = String(e?.message || e);
    // A routing chain has no per-hop deadline, so a real request would wait on
    // this hop: the chain stops here. An unreachable proxy says nothing about
    // the hop, so nothing is claimed about later hops either.
    if (name === "TimeoutError" || name === "AbortError" || /timeout/i.test(msg)) {
      return {
        state: "timeout",
        latencyMs,
        errorMessage: msg,
        chainAction: "stop",
        chainReason: "probe-timeout",
      };
    }
    return {
      state: "network-error",
      latencyMs,
      errorMessage: msg,
      chainAction: "stop",
      chainReason: "proxy-unreachable",
    };
  }

  // TTFB: response headers are back. Stages before this are network/connect +
  // proxy + provider accepting the request.
  const ttfbMs = Date.now() - startedAt;

  if (!response.ok) {
    // The whole body decides the hop (wording rules can sit past the display cut);
    // the first 500 characters are what the probe shows.
    const fullBody = await readBodyText(response);
    const body = fullBody.slice(0, DISPLAY_BODY_CHARS);
    return annotateOAuthHint(
      // A request that was signed and then failed still names its signer.
      {
        ...classifyHttpError(response.status, body, ttfbMs),
        ...signedWithOf(response),
        ...chainDecisionOf(response, fullBody, link.provider),
      },
      link.provider,
      isOAuth
    );
  }

  const streamResult = await consumeProbeStream(response, timeoutMs, startedAt);
  const totalMs = Date.now() - startedAt;

  // Build the granular timing only for a successful read. ttftMs/tokens come
  // from the stream consumer; derive streaming time + throughput here.
  let timing: ProbeTiming | undefined;
  if (
    streamResult.state === "live" &&
    streamResult.ttftMs !== undefined &&
    !streamResult.truncated
  ) {
    const ttftMs = streamResult.ttftMs;
    const tokens = streamResult.tokens ?? 0;
    // Floor the streaming window to STREAM_MS_FLOOR so a near-instant response
    // (TTFT ≈ total) can't produce a nonsense rate. Matches the scale floor.
    const streamMs = Math.max(STREAM_MS_FLOOR, totalMs - ttftMs);
    const tokensPerSec = tokens > 0 ? (tokens / streamMs) * 1000 : 0;
    timing = { ttfbMs, ttftMs, totalMs, tokens, tokensPerSec };
  }

  // Strip the internal stream-only fields (ttftMs/tokens/truncated) before
  // returning the public ProbeResult; the surviving data lives on `timing`.
  const { ttftMs: _ttft, tokens: _tok, truncated: _trunc, ...rest } = streamResult;
  return annotateOAuthHint(
    {
      ...rest,
      latencyMs: totalMs,
      timing,
      ...signedWithOf(response),
      // A failure after a 200: the runtime already handed that 200 to Claude
      // Code, and FallbackHandler never sees a stream-time failure as an error.
      ...(rest.state !== "live"
        ? { chainAction: "stop" as const, chainReason: "after-200" as const }
        : {}),
    },
    link.provider,
    isOAuth
  );
}

/** The `x-claudish-signed-with` the proxy set on this response (ComposedHandler). */
function signedWithOf(response: Response): { signedWith?: string } {
  const raw = response.headers.get("x-claudish-signed-with");
  if (!raw) return {};
  try {
    return { signedWith: decodeURIComponent(raw) };
  } catch {
    return {};
  }
}

/**
 * Attach a login hint when an OAuth provider failed authentication. The
 * `gemini` / `vertex` transports authenticate via cached tokens, so a 401 or
 * a parser error that mentions OAuth usually means the user needs to
 * re-authenticate — surface the exact command instead of leaving them to
 * guess.
 *
 * NOT on a 403. `classifyHttpError` buckets 401 and 403 into the same
 * "auth-failed" state, but they answer different questions: 401 is "I don't
 * know who you are" (a credential problem, which logging in fixes) while 403 is
 * "I know who you are and you are not allowed this" (an entitlement problem,
 * which logging in cannot touch). Prescribing a re-login for the second is an
 * actionably WRONG instruction, and the user burns time on the credential
 * they already hold.
 *
 * Both OAuth providers here follow Google's own status mapping, so the code is
 * a reliable discriminator: an expired/absent ADC token is UNAUTHENTICATED/401,
 * while a missing IAM role, a disabled API, or a region gate is
 * PERMISSION_DENIED/403 — `gcloud auth application-default login` does nothing
 * for any of the latter. We key off the status rather than sniffing the body:
 * prose heuristics are the same class of guess that produced the bug this
 * guards against, and `describeProbeState` now renders the provider's own
 * message anyway, so suppressing the hint leaves the real explanation visible.
 */
function annotateOAuthHint(result: ProbeResult, provider: string, isOAuth: boolean): ProbeResult {
  if (!isOAuth) return result;
  if (result.state === "live") return result;

  // Muse Code's entitlement failure: the login works but the account is not
  // subscribed. Logging in again changes nothing, so the hint is the subscribe
  // link the message names — never a login command.
  if (provider === "meta-muse-code") {
    const subscribe = /no active Muse Code subscription[^:]*: subscribe at (\S+?)\.?$/i.exec(
      result.errorMessage || ""
    );
    if (subscribe)
      return { ...result, state: "auth-failed", actionHint: `subscribe at ${subscribe[1]}` };
  }

  const loginCommand =
    provider === "antigravity"
      ? "claudish login antigravity"
      : provider === "vertex"
        ? "gcloud auth application-default login"
        : // Not a claudish command: the Devin CLI mints the token and claudish
          // reads its credentials file. Naming `claudish login devin` here
          // would send the user to a command that does not exist.
          provider === "devin"
          ? "devin login"
          : provider === "meta-muse-code"
            ? "claudish login muse"
            : undefined;

  if (!loginCommand) return result;

  // Entitlement failure — re-authenticating cannot fix it, so no hint.
  if (result.httpStatus === 403) return result;

  const looksLikeAuthFailure =
    result.state === "auth-failed" ||
    /auth|token|login|credential|unauthor/i.test(result.errorMessage || "");
  if (!looksLikeAuthFailure) return result;

  return {
    ...result,
    state: "auth-failed",
    actionHint: `run: ${loginCommand}`,
  };
}

/** How much of an error body a probe result shows. */
const DISPLAY_BODY_CHARS = 500;

async function readBodyText(response: Response): Promise<string> {
  try {
    return await response.text();
  } catch {
    return "";
  }
}

/**
 * What a routing chain would do after this failed hop: the runtime's own rule
 * (`decideHopFailure`, shared with `FallbackHandler`). A 500 marked
 * `UNHANDLED_ERROR_HEADER` is a hop whose handler threw, which a chain advances past.
 */
function chainDecisionOf(
  response: Response,
  body: string,
  provider: string
): Pick<ProbeResult, "chainAction" | "chainReason"> {
  if (response.headers.get(UNHANDLED_ERROR_HEADER) === "1") {
    const thrown = decideHopFailure({ kind: "thrown" });
    return { chainAction: thrown.action, chainReason: thrown.reason };
  }
  const decision = decideHopFailure({
    kind: "response",
    status: response.status,
    headers: response.headers,
    body,
    provider,
    name: provider,
  });
  return { chainAction: decision.action, chainReason: decision.reason };
}

// `extractUpstreamStatus` used to live here as a private copy. It is shared with
// `fallback-handler.ts` now (#148), because both have to read the same field to
// tell a remapped terminal error apart from a real 400, and two private readers
// of one wire field is how they drift.

/**
 * Pull the Anthropic error `type` (e.g. "connection_error") out of a proxy error
 * body so classification can distinguish a local connection failure from a
 * same-status upstream error (a transient upstream 503 is "server_error"/
 * "overloaded_error", a proxy-side reach failure is "connection_error").
 */
function extractErrorType(body: string): string | undefined {
  if (!body) return undefined;
  try {
    const parsed = JSON.parse(body);
    const t = parsed?.error?.type;
    return typeof t === "string" ? t : undefined;
  } catch {
    return undefined;
  }
}

export function classifyHttpError(status: number, body: string, latencyMs: number): ProbeResult {
  const lowered = body.toLowerCase();
  // A proxy-side connection failure (DNS unresolved, connection refused, host
  // unreachable) is tagged by composed-handler as a **400** connection_error —
  // NOT a 503, whatever this comment said until v9.2.x. That matters twice
  // over. The status is 400 because a 503 makes Claude Code retry with the
  // reason buried behind its own banner, and because `isRetryableError` would
  // otherwise walk the fallback chain. So the test below keys off the `type`,
  // which is status-agnostic and therefore survives both that choice and the
  // terminal-error remap that shares the same 400.
  //
  // Probes never reach the retry ladder at all: `probeLink` sends
  // `x-claudish-no-recovery: 1` and `shouldSkipTier1` honours it, so an
  // unreachable provider still answers here in milliseconds instead of holding
  // for the full recovery deadline and misreporting as a timeout.
  //
  // It is a LOCAL network problem, not an upstream server error — classify it
  // as network-error so the row reads "network error" with the proxy's
  // actionable message ("check your network/DNS") instead of a generic
  // "server error".
  if (extractErrorType(body) === "connection_error") {
    return {
      state: "network-error",
      latencyMs,
      httpStatus: status,
      errorMessage: extractErrorMessage(body) || "Cannot reach provider",
    };
  }
  // A remapped terminal error carries the real upstream code — classify (and
  // display) by THAT, not the proxy's 400 wrapper.
  const upstream = status === 400 ? extractUpstreamStatus(body) : undefined;
  if (status === 401 || status === 403 || upstream === 401 || upstream === 403) {
    const authStatus = upstream ?? status;
    // An auth-shaped status does NOT prove an auth problem. OpenCode Zen Go
    // answers 401 with "Model <id> is not supported" for models it does not
    // carry — measured with a real key, where `zgo@deepseek-v4-pro-0813` 401s
    // while `zgo@kimi-k3` on the SAME key returns 200. Reporting that as
    // `auth-failed` sent the user to check a credential that was working, and
    // buried the live OpenRouter hop sitting further down the same chain.
    //
    // Classified from the BODY, using the same predicate composed-handler's hint
    // uses, so the state and the explanation cannot disagree about one response.
    // The status is preserved: it is what the provider really said, and rewriting
    // it would hide the provider's misuse of 401 rather than explain it.
    if (hasModelUnsupportedWording(body)) {
      return {
        state: "model-not-found",
        latencyMs,
        httpStatus: authStatus,
        errorMessage: extractErrorMessage(body) || `HTTP ${authStatus}`,
      };
    }
    // Nor is it an auth failure when the provider accepted the credential and
    // denied THIS MODEL. Alibaba's Model Studio answers
    // `403 {"code":"Model.AccessDenied","message":"Model access denied."}` while
    // the same key lists 169 models on the same host (measured 2026-09-19), so
    // the credential is proven good by the provider itself. Reported as
    // `auth-failed` it both blamed a working key and STOPPED Test All on the
    // first candidate: the loop retries `error`, never `auth-failed`, so an
    // account that may call some models but not the catalog's pick never got a
    // second try. `error` keeps the failure without the false cause.
    if (/model[^"]{0,24}access[ _-]?denied|access[ _-]?denied[^"]{0,24}model/i.test(body)) {
      return {
        state: "error",
        latencyMs,
        httpStatus: authStatus,
        errorMessage: extractErrorMessage(body) || `HTTP ${authStatus}`,
      };
    }
    // Nor is it an auth failure when the provider handed back a link to act on.
    // Measured: Zen Go answers a model the account has not opted into with
    // `403 RegionError … requires explicit opt in: <url>` — the credential is
    // fine, the model IS in its dynamic models catalog, and the fix is a click. Reporting
    // `auth-failed` there points the user at a working key. `error` keeps the
    // failure semantics (it is in `isFailureState`) without the false cause.
    if (hasActionableLink(body)) {
      return {
        state: "error",
        latencyMs,
        httpStatus: authStatus,
        errorMessage: extractErrorMessage(body) || `HTTP ${authStatus}`,
      };
    }
    return {
      state: "auth-failed",
      latencyMs,
      httpStatus: authStatus,
      errorMessage: extractErrorMessage(body) || `HTTP ${authStatus}`,
    };
  }
  if (status === 404 || /model[_ ]not[_ ]found|no such model|unknown model/.test(lowered)) {
    return {
      state: "model-not-found",
      latencyMs,
      httpStatus: status,
      errorMessage: extractErrorMessage(body) || `HTTP ${status}`,
    };
  }
  if (status === 429) {
    // A 429 is the channel for BOTH transient throttling and a spent flat-rate
    // allowance, so the status alone cannot tell them apart — only the body can.
    // MiniMax Coding answers `429 "Token Plan usage limit reached: Upgrade your
    // Token Plan or purchase Credits for more usage. (2056)"`, which is a plan
    // window, not throttling: retrying in a second cannot help, and the TUI
    // treats throttling as healthy. Wording-gated, so an ordinary throttle with
    // no allowance vocabulary still reads as "rate limited".
    if (hasPlanLimitWording(body)) {
      return {
        state: "plan-limit",
        latencyMs,
        httpStatus: status,
        errorMessage: extractErrorMessage(body) || "Plan allowance spent for this cycle",
      };
    }
    return {
      state: "rate-limited",
      latencyMs,
      httpStatus: status,
      errorMessage: extractErrorMessage(body) || "Rate limited",
    };
  }
  // Out-of-credit, two wire shapes with the same meaning:
  //  - upstream 429 remapped by the proxy: the proxy only remaps TERMINAL 429s
  //    (quota/balance exhaustion per isTerminalError — e.g. Moonshot "suspended
  //    due to insufficient balance", Z.AI code 1113); transient throttling 429s
  //    pass through unremapped and stay "rate-limited" above.
  //  - a direct 402 Payment Required (e.g. a lapsed Kimi Coding plan).
  // NOT an auth bug: the request authenticated fine, the account just can't be
  // billed. Distinct from "rate-limited" because the TUI treats throttling as
  // healthy ("throttled" note) — an exhausted account must read as a failure
  // with an honest cause instead of an opaque "error · 400".
  if (upstream === 429 || status === 402) {
    // Same fork as the raw 429 above, on the remapped shape. This is the path a
    // TUI probe takes, because the proxy turns a terminal 429 into a 400 that
    // carries the real upstream status. A spent SUBSCRIPTION reaching the user
    // as "out of credit" is actively misleading: it sends a flat-rate user to a
    // billing page to fix a plan that is working and resets on its own.
    //
    // 402 is deliberately NOT forked. It means Payment Required, which is a
    // balance fact whatever wording rides along with it.
    if (status !== 402 && hasPlanLimitWording(body)) {
      return {
        state: "plan-limit",
        latencyMs,
        httpStatus: upstream ?? status,
        errorMessage: extractErrorMessage(body) || "Plan allowance spent for this cycle",
      };
    }
    return {
      state: "out-of-credit",
      latencyMs,
      httpStatus: upstream ?? status,
      errorMessage:
        extractErrorMessage(body) || "Out of credit — account balance or plan exhausted",
    };
  }
  if (status >= 500) {
    return {
      state: "server-error",
      latencyMs,
      httpStatus: status,
      errorMessage: extractErrorMessage(body) || `HTTP ${status}`,
    };
  }
  return {
    state: "error",
    latencyMs,
    httpStatus: status,
    errorMessage: extractErrorMessage(body) || `HTTP ${status}`,
  };
}

/**
 * Shorten a provider message WITHOUT severing a URL.
 *
 * A cap is necessary — but a blind cut removed the only actionable part of Zen
 * Go's region error, leaving "…requires explicit opt in:
 * https://opencode.ai/workspa..." on screen. The user is told there is a
 * specific fix and then denied the address of it. So the link is kept whole and
 * the PROSE around it absorbs the cut instead.
 *
 * The cap is sized for the WIDEST consumer, not the narrowest. It was 160,
 * chosen when the only consumer was a one-line probe row — but every consumer
 * now bounds itself (the row clips to its column, the TUI detail panel wraps to
 * 2 lines, `probe-results-printer` word-wraps to `MAX_ERROR_LINES` 4), so 160
 * was no longer protecting a layout, only deleting text. It cut MiniMax
 * Coding's `429 "Token Plan usage limit reached: Upgrade your Token Plan or
 * purchase Credits for more usage. (2056)"` at "Upgrade you..." — losing the
 * remedy, which is the only part of the sentence the user can act on.
 */
function truncateKeepingLink(text: string, max = 400): string {
  if (text.length <= max) return text;
  const url = text.match(/https?:\/\/\S+/i)?.[0];
  if (!url) return `${text.slice(0, max - 3)}...`;
  // Reserve room for the link plus the ellipsis joining it to the trimmed prose.
  const room = max - url.length - 4;
  if (room <= 0) return url;
  // Cut at a word boundary — the prose is being sacrificed for the link, so it
  // should at least end on a whole word rather than "follow the l...".
  const head = text.slice(0, room);
  const lastSpace = head.lastIndexOf(" ");
  const prose = (lastSpace > room * 0.5 ? head.slice(0, lastSpace) : head).trimEnd();
  return `${prose}... ${url}`;
}

/**
 * ONE LINE, always. Every consumer of a probe error message renders it on a
 * single row, and a newline is the one character none of them can survive: the
 * TUI clips by character count, so a `\n` inside the clip ends the row early and
 * everything after it paints over the row below. `truncateKeepingLink` bounds
 * LENGTH, which is a different promise and was mistaken for this one.
 */
function oneLine(text: string): string {
  return text.replace(/\s+/g, " ").trim();
}

/**
 * The message a JSON error document carries, under any of the shapes seen.
 *
 * `error.provider_message` is read FIRST and it is the whole point of this
 * order: it is the upstream's own sentence, while `error.message` beside it is
 * claudish's composed one — the recovery hint, then the provider's text after an
 * em dash. A probe row clips, so composing put the guess where the reader looks
 * and the evidence where they never get to. "Model access denied." is three
 * words and says what happened; "The provider accepted the credential but denied
 * access to this model — check model access or activation for this account in
 * the provider's console, not the key." is 150 characters of inference about it.
 *
 * The hint is not thrown away — `probe-results-printer` still word-wraps the
 * full composed `message` in the Details box, which has the room for both.
 */
function messageFromJson(text: string): string | undefined {
  try {
    const parsed = JSON.parse(text);
    const msg =
      parsed?.error?.provider_message ||
      parsed?.error?.message ||
      parsed?.error?.error?.message ||
      parsed?.message ||
      parsed?.detail;
    return typeof msg === "string" && msg.length > 0 ? msg : undefined;
  } catch {
    return undefined;
  }
}

/**
 * Open an SSE frame if that is what this text is, otherwise hand it back.
 *
 * Applied to the EXTRACTED message and not only to the raw body, because the
 * frame arrives both ways and the JSON ladder hides the second one. A provider
 * answering a stream request with an error may send the frame as the body —
 * caught by parsing the body — but claudish also re-wraps a raw upstream body
 * into `{error:{message: <that body>}}` (`composed-handler.ts`, the auth-retry
 * return). That parses as perfectly good JSON, so `messageFromJson` succeeded
 * and returned a whole wire frame wearing a message field. Measured against
 * dashscope-intl: the row read
 *   `event:error data:{"code":"InvalidParameter","message":"Model access
 *    denied.","request_id":"0d6a48d4-…"}`
 * where "Model access denied." was the entire content.
 */
function unwrapFrame(text: string): string {
  const payload = sseDataPayload(text);
  if (!payload) return text;
  return messageFromJson(payload) ?? payload;
}

function extractErrorMessage(body: string): string | undefined {
  if (!body) return undefined;

  const direct = messageFromJson(body);
  if (direct) return truncateKeepingLink(oneLine(unwrapFrame(direct)));

  // Not a JSON document. It may still be an SSE frame carrying one.
  const unwrapped = unwrapFrame(body);
  const trimmed = oneLine(unwrapped);
  if (!trimmed) return undefined;
  return truncateKeepingLink(trimmed);
}

/**
 * Read the SSE stream just long enough to confirm a valid first content event.
 * We don't accumulate the full response — a single valid data chunk is proof
 * that the entire stack (auth, routing, adapter, transport, parser) works.
 */
/** Internal stream result — carries the extra timing fields that probeLink
 *  folds into ProbeResult.timing. Not part of the public ProbeResult. */
type StreamResult = Omit<ProbeResult, "latencyMs" | "timing"> & {
  /** ms from request start to first content token (only on "live"). */
  ttftMs?: number;
  /** output tokens observed (only on "live"). */
  tokens?: number;
  /** True when the read hit the deadline before the stream closed — totalMs is
   *  the timeout cap, not a real completion, so timing must be omitted. */
  truncated?: boolean;
};

async function consumeProbeStream(
  response: Response,
  timeoutMs: number,
  startedAt: number
): Promise<StreamResult> {
  const body = response.body;
  if (!body) {
    return { state: "error", errorMessage: "empty response body" };
  }

  const reader = body.getReader();
  const decoder = new TextDecoder();
  let buffered = "";
  const deadline = Date.now() + timeoutMs;

  // Throughput instrumentation. Unlike before, we now read the FULL (capped)
  // stream so we can measure tokens/sec — we don't bail at the first token.
  let ttftMs: number | undefined;
  let sawContent = false;
  let textChars = 0; // accumulated streamed text length (token estimate fallback)
  let reportedTokens: number | undefined; // exact count from usage, if provided
  let stopReason: string | undefined; // last stop/finish reason seen on the stream
  let errorVerdict: StreamResult | null = null;
  let completed = false; // true when the stream closed cleanly (not deadline-truncated)

  try {
    while (Date.now() < deadline) {
      const { value, done } = await reader.read();
      if (done) {
        completed = true;
        break;
      }
      buffered += decoder.decode(value, { stream: true });

      const events = buffered.split("\n\n");
      buffered = events.pop() ?? "";

      for (const event of events) {
        const verdict = interpretSseEvent(event);
        if (verdict && typeof verdict === "object" && verdict.state !== "live") {
          // A hard error event mid-stream — surface it immediately.
          errorVerdict = verdict;
          break;
        }
        // Token accounting from the parsed event.
        const acct = accountStreamEvent(event);
        if (acct.contentDelta) {
          if (ttftMs === undefined) ttftMs = Date.now() - startedAt;
          sawContent = true;
        }
        if (acct.textChars) textChars += acct.textChars;
        if (acct.outputTokens !== undefined) reportedTokens = acct.outputTokens;
        if (acct.stopReason) stopReason = acct.stopReason;
      }
      if (errorVerdict) break;
    }
  } catch (e: any) {
    // If we already saw content, a mid-stream read error is non-fatal — the
    // link IS live; we just stop measuring. Otherwise it's a real failure.
    if (!sawContent) {
      return { state: "network-error", errorMessage: String(e?.message || e) };
    }
  } finally {
    try {
      await reader.cancel();
    } catch {
      // ignore
    }
  }

  if (errorVerdict) return errorVerdict;

  if (sawContent) {
    // Prefer the provider-reported token count; otherwise estimate from text
    // length (~4 chars/token is the common rough heuristic).
    const tokens = reportedTokens ?? Math.max(1, Math.round(textChars / 4));
    // The link IS live (it produced tokens). But if we hit the deadline before
    // the stream closed, totalMs == the timeout cap, NOT a real completion time
    // — building timing from it would poison the shared bar scale with a bogus
    // 40s "slowest". Mark it truncated so probeLink omits the timing breakdown.
    return { state: "live", ttftMs, tokens, truncated: !completed };
  }

  // Contentless 200: distinguish token-budget exhaustion from a genuinely dead
  // stream. Reasoning models can burn the whole probe budget on hidden
  // reasoning — the stream signals it either with an explicit truncation stop
  // reason ("max_tokens"/"length") or with usage that consumed the full cap.
  //
  // The explicit reason is now the normal path: openai-sse and gemini-sse both
  // map upstream truncation to "max_tokens" (they previously hardcoded
  // "end_turn", which is why the usage-based fallback below was written). Keep
  // the fallback — it still covers providers that report usage but no
  // finish_reason. A self-explaining message beats a bare "stream ended without
  // content" for what is really a budget artifact, not a dead link.
  const truncationReason =
    stopReason === "max_tokens" || stopReason === "length" ? stopReason : undefined;
  if (truncationReason || (reportedTokens !== undefined && reportedTokens >= PROBE_MAX_TOKENS)) {
    const cause = truncationReason
      ? `finish: ${truncationReason}`
      : `${reportedTokens} tokens consumed, none visible`;
    return {
      state: "error",
      errorMessage: `no visible output within probe budget (${cause})`,
    };
  }

  return { state: "error", errorMessage: "stream ended without content" };
}

/**
 * Token-accounting view of one SSE event (Claude `/v1/messages` format — the
 * proxy normalizes every provider to this). Returns whether the event carried
 * a content delta (for TTFT), how much text it added (token estimate), any
 * exact `output_tokens` usage figure, and any stop/finish reason the provider
 * reported (used to explain contentless budget-truncated streams).
 */
function accountStreamEvent(rawEvent: string): {
  contentDelta: boolean;
  textChars: number;
  outputTokens?: number;
  stopReason?: string;
} {
  let dataPayload = "";
  for (const line of rawEvent.split("\n")) {
    if (line.startsWith("data:")) dataPayload += line.slice(5).trim();
  }
  if (!dataPayload || dataPayload === "[DONE]") {
    return { contentDelta: false, textChars: 0 };
  }
  let parsed: any;
  try {
    parsed = JSON.parse(dataPayload);
  } catch {
    return { contentDelta: false, textChars: 0 };
  }

  let textChars = 0;
  let contentDelta = false;

  // Claude content_block_delta: { delta: { type: "text_delta", text: "..." } }
  const text =
    parsed?.delta?.text ??
    (Array.isArray(parsed?.choices) ? parsed.choices[0]?.delta?.content : undefined);
  if (typeof text === "string" && text.length > 0) {
    contentDelta = true;
    textChars = text.length;
  } else if (parsed?.type === "content_block_delta") {
    contentDelta = true;
  } else if (parsed?.type === "content_block_start") {
    // A block that has only been OPENED is not output yet. Every `text` and
    // `thinking` block starts empty and is filled by the deltas above, which are
    // counted on their own — so counting the start as well only ever moves TTFT
    // earlier than the first token.
    //
    // It became load-bearing when openai-sse started emitting an EMPTY text block
    // for a turn that ended normally having produced nothing (so that `content`
    // is never an empty array, a shape Anthropic's API does not produce). That
    // block carries no delta, and counting it as visible output reported a model
    // that said nothing as a healthy link — which is the exact reading this
    // function exists to prevent.
    //
    // A `tool_use` start is the exception: the block start IS the call, and a
    // tool call is output.
    contentDelta = parsed.content_block?.type === "tool_use";
  }

  // Exact usage: Claude reports cumulative output_tokens on message_delta /
  // message_start.usage; OpenAI-shaped streams put it on a trailing usage chunk.
  const outputTokens =
    parsed?.usage?.output_tokens ??
    parsed?.message?.usage?.output_tokens ??
    parsed?.usage?.completion_tokens;

  // Claude message_delta carries delta.stop_reason; OpenAI-shaped streams put
  // finish_reason on the choice.
  const stopReason =
    parsed?.delta?.stop_reason ??
    (Array.isArray(parsed?.choices) ? parsed.choices[0]?.finish_reason : undefined);

  return {
    contentDelta,
    textChars,
    outputTokens: typeof outputTokens === "number" ? outputTokens : undefined,
    stopReason: typeof stopReason === "string" ? stopReason : undefined,
  };
}

type SseVerdict = "live" | Omit<ProbeResult, "latencyMs"> | null;

function interpretSseEvent(rawEvent: string): SseVerdict {
  const lines = rawEvent.split("\n");
  let eventType = "";
  let dataPayload = "";
  for (const line of lines) {
    if (line.startsWith("event:")) eventType = line.slice(6).trim();
    else if (line.startsWith("data:")) dataPayload += line.slice(5).trim();
  }
  if (!dataPayload) return null;
  if (dataPayload === "[DONE]") return null;

  let parsed: any;
  try {
    parsed = JSON.parse(dataPayload);
  } catch {
    return null;
  }

  if (parsed?.type === "error" || eventType === "error" || parsed?.error) {
    const message =
      parsed?.error?.message ||
      parsed?.error?.error?.message ||
      parsed?.message ||
      "provider returned error event";
    const status = parsed?.error?.status || parsed?.status;
    if (typeof status === "number") {
      return {
        state: status === 401 || status === 403 ? "auth-failed" : "error",
        httpStatus: status,
        errorMessage: message,
      };
    }
    return { state: "error", errorMessage: message };
  }

  if (isContentEvent(parsed, eventType)) {
    return "live";
  }
  return null;
}

function isContentEvent(parsed: any, eventType: string): boolean {
  if (eventType === "content_block_start" || eventType === "content_block_delta") return true;
  if (eventType === "message_start") return true;
  if (parsed?.type === "content_block_start") return true;
  if (parsed?.type === "content_block_delta") return true;
  if (parsed?.type === "message_start") return true;
  if (parsed?.type === "message_delta") return true;
  if (Array.isArray(parsed?.choices) && parsed.choices.length > 0) {
    const choice = parsed.choices[0];
    if (choice?.delta || choice?.message || choice?.text || choice?.finish_reason) return true;
  }
  if (parsed?.candidates) return true;
  return false;
}

/**
 * Append the upstream's own explanation to a status line when we have one.
 *
 * Every failure state carries the provider's `errorMessage`, but only "error"
 * used to render it — the status-bearing states printed the code and threw the
 * message away. That silently hid the one sentence that says what to DO: an
 * OpenCode Zen Go probe against a region-locked model answered 403 with
 * "only available hosted in China and requires explicit opt in: <url>", and the
 * row read a bare "auth failed · 403" on a key that was working fine. A 4xx is
 * a bucket, not a diagnosis; the body is the diagnosis.
 */
function withDetail(base: string, message?: string): string {
  return message ? `${base} — ${stripRedundantHead(message)}` : base;
}

/**
 * Drop the `"<Provider> error (HTTP <status>): "` head claudish put on its own
 * message, because `base` has just said both of those things.
 *
 * The head is composed by `composeErrorMessage` for the proxy's stderr line and
 * for the body it returns to Claude Code, where naming the provider and the code
 * is the whole point — nothing else on that line does. A probe row is the
 * opposite situation: the provider is the row's own left column and the status is
 * the first thing `base` prints, so the head repeats 30 columns of what the
 * reader can already see, and 30 columns is what the row has left for the part
 * that says what to DO. Measured on `--probe qwen3.8-max` at 130 columns: the
 * summary row ended at "…accepted the credential but c", cutting the sentence
 * exactly where it turns actionable.
 *
 * Anchored to the full composed shape, not to " error" or the provider name: a
 * provider's own prose has to match `(HTTP <3 digits>): ` to be touched, and no
 * upstream message observed does.
 */
function stripRedundantHead(message: string): string {
  return message.replace(/^.{1,40}? error \(HTTP \d{3}\): /, "");
}

export function describeProbeState(result: ProbeResult): string {
  const status = result.httpStatus ?? "";
  const latency = result.latencyMs ? ` · ${result.latencyMs}ms` : "";
  switch (result.state) {
    case "live":
      return `live · ${result.latencyMs}ms`;
    case "key-missing":
      return result.errorMessage ? `missing (${result.errorMessage})` : "missing";
    case "auth-failed":
      return withDetail(`auth failed · ${status}${latency}`.trim(), result.errorMessage);
    case "model-not-found":
      return withDetail(`model not found · ${status}${latency}`.trim(), result.errorMessage);
    case "rate-limited":
      return withDetail(`rate limited · ${result.latencyMs}ms`, result.errorMessage);
    case "out-of-credit":
      return withDetail(`out of credit · ${status}${latency}`.trim(), result.errorMessage);
    case "plan-limit":
      // "plan limit reached", not "out of credit": the account can be billed,
      // the allowance simply has not reset. The provider's own sentence follows,
      // and it is the part that names the plan and the way out.
      return withDetail(`plan limit reached · ${status}${latency}`.trim(), result.errorMessage);
    case "server-error":
      return withDetail(`server error · ${status} · ${result.latencyMs}ms`, result.errorMessage);
    case "timeout":
      return withDetail(`timeout · ${result.latencyMs}ms`, result.errorMessage);
    case "network-error":
      return withDetail(`network error · ${result.latencyMs}ms`, result.errorMessage);
    case "error": {
      // Append the specific cause when present. Without this, a contentless
      // stream (e.g. a reasoning model that spent its whole budget before any
      // visible text — HTTP 200, so no status code) rendered as a bare
      // "error · Nms" with the explanatory errorMessage silently dropped.
      const base = `error${result.httpStatus ? ` · ${result.httpStatus}` : ""}${latency}`;
      return withDetail(base, result.errorMessage);
    }
  }
}

export function isReadyState(state: ProbeState): boolean {
  return state === "live";
}

export function isFailureState(state: ProbeState): boolean {
  return (
    state === "auth-failed" ||
    state === "model-not-found" ||
    state === "rate-limited" ||
    state === "out-of-credit" ||
    state === "plan-limit" ||
    state === "server-error" ||
    state === "timeout" ||
    state === "network-error" ||
    state === "error"
  );
}