Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

67.3 KB
Raw Blame
import {
  BaseExecutor,
  type ExecuteInput,
  type ExecutorExecuteResult,
  type ProviderCredentials,
} from "./base.ts";
import { PROVIDERS } from "../config/constants.ts";
import { getModelTargetFormat, stripOpencodeModelPrefix } from "../config/providerModels.ts";
import {
  injectReasoningContentForThinkingModel,
  isThinkingMessageModel,
} from "../utils/reasoningContentInjector.ts";
import {
  hasAmbientProxyContext,
  currentAppliedProxySink,
  runWithDirectFetchContext,
  runWithProxyContext,
  noteRotationAccount,
  noteAddedWait,
  resolveProxyForRequest,
  type AddedWaitCause,
} from "../utils/proxyFetch.ts";
import {
  createServedAccountTracker,
  noteParkWait,
  noteReplayed,
  noteStoredFallback,
} from "./opencodeResilienceNotes.ts";
import {
  clientSuppliedOpencodeSession,
  forwardOpencodeClientHeaders,
  resolveOpencodeCliDefaults,
} from "../utils/opencodeHeaders.ts";
import { projectOpencodeSessionBody } from "../utils/opencodeSessionIdentity.ts";
import { listForRequest, releaseRequestList } from "./opencodeAccountScope.ts";
import { applyOpencodeToolNameLengthAliases } from "./toolNameLengthAlias.ts";
import type { ScopedAccount, ScopedAccountHealth } from "./opencodeAccountScope.ts";
import { guardRequiredAccountProxies } from "./opencodeRequiredProxy.ts";
import {
  type AccountProxyConfig,
  type RotationAccountSnapshot,
  pickAccount as pickRotatableAccount,
  maskAccountId,
  isNetworkErrorRotatable,
  isEmptyUpstreamRejection,
  extractChatcmplId,
  recordRotationSnapshot,
} from "./accountRotation.ts";
import {
  markCooldown,
  markOutcome,
  markSuccess,
  noteResponseServed,
} from "./opencodeAccountHealth.ts";
import {
  isOpencodeGeoBlocked,
  proxyKeyOf,
  poolReselectKeyOf,
  isOpencodeUserBlocked,
} from "./opencodeGeoBlock.ts";
import {
  FREE_TIER_INFERENCE_BASE_URL,
  attemptFor,
  isGatedFreeTierRequest,
  isPremiumOpencodeModel,
  noteFreeTierOutcome,
  prepareFreeTierRequest,
  rebuildJsonFromForcedStream,
  surfaceFromBaseUrl,
} from "./opencodeFreeTierContract.ts";
import {
  applyOpencodeOutputBudgetFloors,
  createMuseSparkStreamFinishNormalizer,
  isResponsesTerminalLine,
  normalizeMuseSparkFinishReason,
} from "./opencodeMuseSpark.ts";
import { currentRequestContext, runInRequestContext } from "./opencodeRequestContext.ts";
import {
  handleLoopFreeTierRefusal,
  isOwnToolsRetryableRefusal,
  retryFreeTierRefusalWithObservedTools,
} from "./opencodeFreeTierRetry.ts";
import { withRequestShapeRetry } from "./opencodeRequestShape.ts";
import { trimOversizedToolEnums } from "./opencodeEnumTrim.ts";

// Re-exported: the free-model catalog moved to the contract module (it decides whether the
// contract applies), and existing importers keep resolving it from the executor.
export { isPremiumOpencodeModel };
import {
  isResponsesFirstByteTimeout,
  makeStallGuardedCall,
  setupStallGuard,
} from "./opencodeResponsesStall.ts";
import { discardResponseBody } from "./opencodeResponseBody.ts";
import { headersWaitDispatch, headersWaitState } from "./opencodeHeadersWait.ts";
import {
  isRetriableUpstreamFailure,
  releaseResponseBody,
  sleepAbortable,
  transientRetryDelayMs,
} from "./opencodeTransientFailure.ts";
import { isProxyAvoided } from "../utils/proxyRefusalMemory.ts";
import * as egressPacing from "./opencodeEgressThrottle.ts";
import {
  isNetworkRotationSharedEgressGuardEnabled,
  isProxySkipRecentlyFailedEnabled,
  isRotationAttributionEnabled,
  isOpencodeUserBlockedRotationEnabled,
  isOpencodeTransientFailoverBackoffEnabled,
  isOpencodeRateLimited429EarlyStopEnabled,
  isOpencodeParkAndResumeEnabled,
  isOpencodePoolReselectEnabled,
  isOpencodePublishedCatalogRoutingEnabled,
  isOpencodeV2ClientFingerprintEnabled,
} from "@/shared/utils/featureFlags";
import { setPublishedCatalogRoutingGate } from "../utils/opencodePublishedCatalog.ts";
import { isEgressBucketedLockScope } from "../config/providerErrorRules.ts";
import {
  BURST_PARK_THRESHOLD,
  parkWaitMs,
  readPoolStrainMarker,
  runParkAndReplay,
  setAsideParkWaitMs,
} from "./opencodeParkResume.ts";

/**
 * The main OpenCode Zen host, shared by the `opencode` and `opencode-zen`
 * registry entries. Used to scope the `x-api-key` auth override (#12633) away
 * from `opencode-go`, which serves a different upstream (`.../zen/go/v1`).
 */
const ZEN_BASE_URL = "https://opencode.ai/zen/v1";

/**
 * Per-account proxy configuration, persisted by NoAuthAccountCard under
 * `providerSpecificData.accountProxies` (keyed by the account id, which the UI
 * stores in `providerSpecificData.fingerprints`). Same shape mimocode uses.
 */
export type OpencodeAccountProxyConfig = AccountProxyConfig;

export type { ScopedAccount as OpencodeAccountState };

const EFFORT_LEVELS = ["none", "low", "high", "max"] as const;

/**
 * Models on opencode-go that support effort-tier aliases. Each entry maps the
 * canonical base id to the set of effort suffixes the upstream supports.
 *
 * - DeepSeek V4 Pro and Flash: none/low/high/max
 * - glm-5.2: high/max only (Z.AI maps these through the reasoning plane;
 *   low/medium are not supported on the OpenAI transport)
 * - mimo-v2.5: high/max only (same reasoning; Xiaomi MiMo does not document
 *   low/medium effort tiers)
 * - #8353 OpenCode Go registry effort variants (exact suffix sets from
 *   `opencode models opencode-go --verbose`; MiniMax M3 excluded — different
 *   thinking-mode mapping):
 *   grok-4.5 low/medium/high; hy3 none/low/high; kimi-k3 max;
 *   qwen3.6-plus / qwen3.7-max / qwen3.7-plus high/max;
 *   muse-spark-1.2-contributor minimal/low/medium/high/xhigh (no max)
 * - #12674 Muse Spark 1.3 Contributor: minimal/low/medium/high/xhigh (no max),
 *   verified via `opencode models opencode-go --refresh --verbose`
 */
const EFFORT_TIERS: Record<string, readonly string[]> = {
  "deepseek-v4-pro": EFFORT_LEVELS,
  "deepseek-v4-flash": EFFORT_LEVELS,
  "glm-5.2": ["high", "max"],
  "mimo-v2.5": ["high", "max"],
  "grok-4.5": ["low", "medium", "high"],
  hy3: ["none", "low", "high"],
  "kimi-k3": ["max"],
  "qwen3.6-plus": ["high", "max"],
  "qwen3.7-max": ["high", "max"],
  "qwen3.7-plus": ["high", "max"],
  "muse-spark-1.2-contributor": ["minimal", "low", "medium", "high", "xhigh"],
  "muse-spark-1.3-contributor": ["minimal", "low", "medium", "high", "xhigh"],
};

/**
 * Parse a model string with an effort-level suffix.
 * e.g. "deepseek-v4-pro-low" → { baseModel: "deepseek-v4-pro", effort: "low" }
 *      "glm-5.2-high"         → { baseModel: "glm-5.2", effort: "high" }
 * Returns null if the model doesn't match any known effort-tier pattern.
 */
export function parseEffortLevel(model: string): { baseModel: string; effort: string } | null {
  const m = String(model || "");
  for (const [baseModel, levels] of Object.entries(EFFORT_TIERS)) {
    for (const level of levels) {
      if (m === `${baseModel}-${level}`) {
        return { baseModel, effort: level };
      }
    }
  }
  return null;
}

// #16798: the published-catalog surface lookup in providerModels.ts is client-reachable and
// cannot import the server flag resolver; this executor (always loaded with the chat
// pipeline) hands it the OPENCODE_PUBLISHED_CATALOG_ROUTING_ENABLED reader. Unregistered
// (client bundle) reads as off.
setPublishedCatalogRoutingGate(isOpencodePublishedCatalogRoutingEnabled);

/**
 * Resolves the registry `targetFormat` for a model, aliasing `provider` first.
 *
 * `PROVIDER_MODELS` is keyed by the provider's public ALIAS (e.g. `"opencode-zen"`), not its
 * raw registry id (e.g. `"opencode"`) — mirrors `resolveChatCoreTargetFormat()`
 * (`handlers/chatCore/targetFormat.ts`), which already aliases before calling
 * `getModelTargetFormat()`. Calling it with the raw id here made every entry miss
 * silently (fell through to `"openai"`), while chatCore's own request-body
 * translation (correctly aliased) still switched to the Responses API shape for
 * `targetFormat:"openai-responses"` models — sending a Responses-shaped body to
 * the `/chat/completions` URL this executor's own `buildUrl()` kept selecting.
 * Exported for testability.
 */
export function resolveOpencodeTargetFormat(provider: string, model: string): string {
  return getModelTargetFormat(provider, model) || "openai";
}

export {
  MUSE_SPARK_MIN_OUTPUT_TOKENS,
  applyMuseSparkMinOutputTokens,
  createMuseSparkStreamFinishNormalizer,
  normalizeMuseSparkFinishReason,
} from "./opencodeMuseSpark.ts";

export class OpencodeExecutor extends BaseExecutor {
  /** Delegates to `isPremiumOpencodeModel`. Exported for testability. */
  static isPremiumModel(model: string, provider: string): boolean {
    return isPremiumOpencodeModel(model, provider);
  }

  /**
   * Note the outcome of a forced-stream response without reading its body: a success
   * confirms the borrowed shape, anything else carries no verdict (the paths that hold
   * the verdict note it explicitly where they already read it).
   */
  private noteForcedStreamOutcome(input: ExecuteInput, result: ExecutorExecuteResult): void {
    const attempt = attemptFor(input.body);
    const response =
      result instanceof Response ? result : "response" in result ? result.response : null;
    noteFreeTierOutcome(attempt, {
      ok: !!response?.ok,
      status: response?.ok ? (response.status ?? null) : null,
      bodyText: null,
    });
  }

  /**
   * The target format and the client session of the request being served. While `execute()`
   * runs they live in that request's own context (this instance is shared and requests
   * overlap); outside it they fall back to plain fields, which is how `buildHeaders`,
   * `buildUrl` and `transformRequest` are exercised on their own.
   */
  private _formatFallback: string | null = null;
  private _sessionFallback: string | undefined;
  get _requestFormat(): string | null {
    return currentRequestContext()?.format ?? this._formatFallback;
  }
  set _requestFormat(value: string | null) {
    const context = currentRequestContext();
    if (context) context.format = value;
    else this._formatFallback = value;
  }
  private get _clientSession(): string | undefined {
    const context = currentRequestContext();
    return context ? context.session : this._sessionFallback;
  }
  private set _clientSession(value: string | undefined) {
    const context = currentRequestContext();
    if (context) context.session = value;
    else this._sessionFallback = value;
  }
  private _surface = () => surfaceFromBaseUrl(this.config?.baseUrl);

  /** Free-tier retry context: the request-scoped contract state the retry helper needs. */
  private freeTierRetryCtx(input: ExecuteInput) {
    // #14148 moved the contract attempt off the executor: it is keyed by the
    // request body, so read it back from there instead of a shared field.
    const attempt = attemptFor(input.body);
    return {
      surface: this._surface(),
      provider: this.provider,
      requestFormat: this._requestFormat,
      clientSession: this._clientSession,
      borrowed: attempt?.borrowed,
      clientToolNames: attempt?.clientToolNames ?? [],
      v2Fingerprint: isOpencodeV2ClientFingerprintEnabled(),
    };
  }

  // Not `private`: passed as the shared pick cursor to
  // pickRotatableAccount(), which needs a plain `{ nextAccountIdx }` shape —
  // TS's private-member nominal check rejects `this` there otherwise.
  nextAccountIdx = 0;
  // Member health shared across requests on this alias, keyed by member id.
  // Each request still walks its own list (see `opencodeAccountScope.ts`).
  accountHealth = new Map<string, ScopedAccountHealth>();
  get accounts(): ScopedAccount[] {
    const store = this.accountHealth;
    // Cold parity with the historical default direct member (read-only).
    if (store.size === 0) {
      return [{ fingerprint: "", cooldownUntil: 0, consecutiveFails: 0, proxy: null }];
    }
    const live = [...store.entries()].map(([fingerprint]) => ({
      fingerprint,
      get cooldownUntil() {
        return store.get(fingerprint)?.cooldownUntil ?? 0;
      },
      set cooldownUntil(value: number) {
        const current = store.get(fingerprint) ?? { cooldownUntil: 0, consecutiveFails: 0 };
        store.set(fingerprint, { ...current, cooldownUntil: value });
      },
      get consecutiveFails() {
        return store.get(fingerprint)?.consecutiveFails ?? 0;
      },
      set consecutiveFails(value: number) {
        const current = store.get(fingerprint) ?? { cooldownUntil: 0, consecutiveFails: 0 };
        store.set(fingerprint, { ...current, consecutiveFails: value });
      },
      proxy: null as ScopedAccount["proxy"],
    }));
    return live;
  }
  // Sleep used by the opt-in transient failover pause (#13615). Not `private`:
  // tests swap in a recording fake instead of waiting on real timers.
  transientPauseSleep: (ms: number, signal?: AbortSignal | null) => Promise<boolean> =
    sleepAbortable;
  parkSleep: (ms: number, signal?: AbortSignal | null) => Promise<boolean> = sleepAbortable;

  constructor(provider: string) {
    super(provider, PROVIDERS[provider] || PROVIDERS.openai);
  }

  /** Round-robin pick from this request's list, skipping members not ready. */
  private pickAccountWith(
    accounts: ScopedAccount[],
    isReady: (account: ScopedAccount) => boolean,
    keyOfMember?: (account: ScopedAccount) => string | null
  ): ScopedAccount {
    return pickRotatableAccount(accounts, this, isReady, keyOfMember);
  }

  /** Snapshot entries for the attribution registry — ids already masked. */
  private snapshotEntries(
    accounts: ScopedAccount[],
    nowMs: number = Date.now()
  ): RotationAccountSnapshot[] {
    return accounts.map((a) => ({
      masked: maskAccountId(a.fingerprint),
      ready: a.cooldownUntil <= nowMs,
      cooldownUntilMs: a.cooldownUntil > nowMs ? a.cooldownUntil : null,
      consecutiveFails: a.consecutiveFails,
    }));
  }

  /** Emit one info line per cooldown-skipped account seen this request. */
  private logSkippedCooldownAccounts(
    log: { info?: (...args: unknown[]) => void } | undefined,
    cid: string,
    skippedCooldown: Map<string, number>
  ): void {
    for (const [fp, until] of skippedCooldown) {
      const remainingS = Math.max(0, Math.ceil((until - Date.now()) / 1000));
      log?.info?.(
        "OPENCODE",
        `${cid}skipped account ${maskAccountId(fp)} (cooling down, ${remainingS}s remaining)`
      );
    }
  }

  /**
   * Rewrite muse-spark's bogus `finish_reason:"length"` (see the
   * normalizeMuseSparkFinishReason note) to `"stop"` on both streaming and
   * non-streaming success responses. Non-muse-spark models pass through
   * untouched.
   */
  /**
   * Hand a JSON caller a JSON body even though the free-tier contract forced the upstream
   * request to stream. A streaming caller, a refusal and an already-JSON body pass through.
   */
  private finalizeForcedStream(
    input: ExecuteInput,
    result: ExecutorExecuteResult
  ): ExecutorExecuteResult {
    this.noteForcedStreamOutcome(input, result);
    if (input.stream) return result;
    if (!(result instanceof Response)) {
      if (!("response" in result) || !result.response) return result;
    }
    // Non-null exactly when the contract applied: stands in for the old surface/model guard.
    const model = attemptFor(input.body)?.model;
    if (!model) return result;
    if (result instanceof Response) {
      const rebuilt = rebuildJsonFromForcedStream(result, this._requestFormat, model);
      return rebuilt === result ? result : rebuilt;
    }
    const rebuilt = rebuildJsonFromForcedStream(result.response, this._requestFormat, model);
    return rebuilt === result.response ? result : { ...result, response: rebuilt };
  }

  /**
   * Count a refusal that says something about the borrowed tools, on a path
   * that already holds the verdict. Only 403/451 carry that verdict, so only
   * they pay for a body read — anything else leaves the store alone.
   */
  private async noteFreeTierRefusal(
    input: ExecuteInput,
    response: Response,
    log: ExecuteInput["log"]
  ): Promise<void> {
    const attempt = attemptFor(input.body);
    if (!attempt || !attempt.borrowed || attempt.probe) return;
    if (response.status !== 403 && response.status !== 451) return;
    let bodyText: string | null = null;
    try {
      bodyText = await response.clone().text();
    } catch {
      log?.debug?.("OPENCODE", "body read failed on borrowed-shape check");
    }
    noteFreeTierOutcome(attempt, { ok: false, status: response.status, bodyText });
  }

  private normalizeMuseSparkResponse(
    input: ExecuteInput,
    result: ExecutorExecuteResult
  ): ExecutorExecuteResult {
    const model = String(input.model ?? "");
    if (!model.startsWith("muse-spark")) return result;
    if (!("response" in result) || !result.response?.ok || !result.response.body) return result;
    const bodyObj =
      input.body && typeof input.body === "object" && !Array.isArray(input.body)
        ? (input.body as Record<string, unknown>)
        : null;
    const rawBudget = bodyObj?.max_tokens;
    const budget = typeof rawBudget === "number" && Number.isFinite(rawBudget) ? rawBudget : null;
    const response = result.response;
    const isSse = response.headers.get("content-type")?.includes("event-stream") ?? false;

    if (!isSse) {
      // Non-streaming JSON: rewrite in a buffered pass.
      const stream = new ReadableStream<Uint8Array>({
        async start(controller) {
          try {
            const text = await response.clone().text();
            let out = text;
            try {
              const parsed = JSON.parse(text) as Record<string, unknown>;
              normalizeMuseSparkFinishReason(parsed, budget);
              out = JSON.stringify(parsed);
            } catch {
              /* not JSON — forward verbatim */
            }
            controller.enqueue(new TextEncoder().encode(out));
          } catch (err) {
            controller.error(err);
            return;
          }
          controller.close();
        },
      });
      return {
        ...result,
        response: new Response(stream, {
          status: response.status,
          statusText: response.statusText,
          headers: response.headers,
        }),
      };
    }

    // Streaming SSE: line-buffered passthrough with finish_reason rewriting.
    const normalizer = createMuseSparkStreamFinishNormalizer(budget);
    const decoder = new TextDecoder();
    const encoder = new TextEncoder();
    let buffer = "";
    const reader = response.body.getReader();
    let closed = false;
    const stream = new ReadableStream<Uint8Array>({
      async start(controller) {
        try {
          while (!closed) {
            const { done, value } = await reader.read();
            if (done) {
              buffer += decoder.decode();
              if (buffer.length > 0 && !closed) {
                controller.enqueue(encoder.encode(normalizer(buffer)));
              }
              if (!closed) {
                closed = true;
                controller.close();
              }
              return;
            }

            buffer += decoder.decode(value, { stream: true });
            const lines = buffer.split("\n");
            buffer = lines.pop() ?? "";
            for (const line of lines) {
              const normalized = normalizer(line);
              controller.enqueue(encoder.encode(normalized + "\n"));
              if (isResponsesTerminalLine(line)) {
                // OpenCode Zen may ping after response.completed and hold the socket.
                // Close on that terminal event so Chat Completions is not held open.
                closed = true;
                void reader.cancel().catch(() => undefined);
                controller.enqueue(encoder.encode("\n"));
                controller.close();
                return;
              }
            }
          }
        } catch (err) {
          if (!closed) {
            closed = true;
            controller.error(err);
          }
        }
      },
      cancel(reason) {
        closed = true;
        reader.cancel(reason).catch(() => undefined);
      },
    });
    return {
      ...result,
      response: new Response(stream, {
        status: response.status,
        statusText: response.statusText,
        headers: response.headers,
      }),
    };
  }

  async execute(input: ExecuteInput) {
    try {
      return await runInRequestContext(() => {
        // Pool re-selection resolver published by the chat layer on the
        // applied-proxy capture sink (present only when the resolved egress
        // came from a live connection pool). Copied once per request so the
        // 429 arm below reads a synchronous field, never the ALS in a loop.
        const reselect = currentAppliedProxySink()?.reselectPoolMember;
        const ctx = currentRequestContext();
        if (ctx && typeof reselect === "function") ctx.reselectPoolMember = reselect;
        return withRequestShapeRetry(input, (i) => this.executeOnce(i));
      });
    } finally {
      releaseRequestList(input.body, this.accountHealth);
    }
  }

  private async executeOnce(input: ExecuteInput) {
    this._requestFormat = resolveOpencodeTargetFormat(this.provider, input.model);

    // #8681: Gate premium opencode models behind a usable API key.
    // When the connection is keyless (no apiKey, no accessToken) and the model
    // is a premium model (not on the free tier), return a clear 402 error
    // instead of proxying the raw upstream 401 "Missing API key" response.
    const creds = input.credentials;
    const isKeyless =
      !creds?.apiKey && !creds?.accessToken && !creds?.providerSpecificData?.extraApiKeys;
    if (isKeyless && isPremiumOpencodeModel(input.model, this.provider)) {
      const bodyJson = JSON.stringify({
        error: {
          message: "This model requires an opencode API key — add one in Settings → Providers.",
          type: "invalid_request_error",
          code: "premium_model_requires_key",
        },
      });
      return {
        response: new Response(bodyJson, {
          status: 402,
          headers: { "Content-Type": "application/json" },
        }),
        url: "",
        headers: {} as Record<string, string>,
        transformedBody: null,
      };
    }

    try {
      // muse-spark reasoning models consume the entire output budget on hidden
      // server-side reasoning; small caller budgets come back as empty-message
      // 200s ("Provider returned empty content"). Raise tiny budgets to the
      // floor before dispatch (see applyOpencodeOutputBudgetFloors).
      if (input.body && typeof input.body === "object" && !Array.isArray(input.body)) {
        applyOpencodeOutputBudgetFloors(
          String(input.model ?? ""),
          input.body as Record<string, unknown>
        );
      }

      const accounts = listForRequest(input.body, this.accountHealth, input.credentials);
      if (accounts.length === 1 && accounts[0]?.fingerprint === "") this.nextAccountIdx = 0;
      else if (this.nextAccountIdx >= accounts.length) this.nextAccountIdx = 0;
      const { log } = input;
      // Request-scoped attribution prefix for rotation logs: message head,
      // empty when absent (never n/a/none/fabricated). The existing motif
      // stays byte-identical after the prefix.
      const cid = input.correlationId ? `correlationId=${input.correlationId} ` : "";
      const proxyGuard = guardRequiredAccountProxies(input.credentials, accounts, log, cid);
      if (proxyGuard) return proxyGuard;
      // Rotation attribution diagnostics (single flag read per request — the DB
      // override lookup is synchronous SQLite, never in the attempt loop).
      const attributionOn = isRotationAttributionEnabled();
      // Opt-in pool re-selection on a per-address 429 (default off): one flag
      // read per request, like the attribution flag above — never in the loop.
      const poolReselectOn = isOpencodePoolReselectEnabled();
      // Resolver published by the chat layer when the ambient egress came from
      // a live connection pool (undefined otherwise). Read once per request.
      const poolReselect =
        poolReselectOn && isEgressBucketedLockScope(this.provider) && hasAmbientProxyContext()
          ? (currentRequestContext()?.reselectPoolMember ?? null)
          : null;
      // Key of the ambient pool member this request egressed through (null when
      // direct): a resolver answer for the same member is ignored silently.
      let lastPoolKey = poolReselectKeyOf(currentAppliedProxySink()?.proxy);
      // Cooldown-skipped accounts seen this request, keyed by fingerprint (a
      // mask prefix could theoretically collide; masking happens at write).
      const skippedCooldown = new Map<string, number>();

      const hasProxies = accounts.some((a) => a.proxy !== null);
      // Opt-in Responses first-byte stall guard; 0 = no-op.
      const stallWindowMs = setupStallGuard(input.stream, this._requestFormat, log, cid).windowMs;
      const guardStall = makeStallGuardedCall(
        input.stream,
        this._requestFormat,
        stallWindowMs,
        input.signal,
        log,
        cid
      );
      const headersWait = headersWaitState(
        input,
        this._requestFormat,
        this.getTimeoutMs(),
        this.config?.fetchStartTimeoutCapMs
      );
      // Fast path: no multi-account proxy wiring configured → original behavior,
      // plus exactly ONE bounded retry when the upstream answers a 400 empty
      // rejection (same predicate and logging as the rotation loop). Everything
      // else passes untouched: this path deliberately preserves BaseExecutor's
      // intra-URL 429 retries (no skipUpstreamRetry here).
      if (accounts.length === 1 && !hasProxies) {
        // #11894: a connection-level proxy assignment (proxy_assignments) reaches
        // the executor as the AMBIENT proxy context — the chat handler wraps
        // execute() in runWithProxyContext(proxyInfo.proxy, ...) before we run.
        // Only pin direct egress when no such context exists; otherwise let the
        // ambient proxy stand instead of clobbering it with the direct sentinel.
        const dispatch = () => super.execute(input);
        const single = (await guardStall(
          await (hasAmbientProxyContext() ? dispatch() : runWithDirectFetchContext(dispatch))
        )) as HttpExecuteResult;
        const retryAfterRefusal = await retryFreeTierRefusalWithObservedTools(
          this.freeTierRetryCtx(input),
          input,
          single,
          log,
          cid,
          (retryInput) =>
            guardStall(
              hasAmbientProxyContext()
                ? super.execute(retryInput)
                : runWithDirectFetchContext(() => super.execute(retryInput))
            ) as unknown as Promise<HttpExecuteResult>
        );
        if (retryAfterRefusal) {
          await this.noteFreeTierRefusal(input, retryAfterRefusal.response, log);
          return this.finalizeForcedStream(
            input,
            this.normalizeMuseSparkResponse(input, retryAfterRefusal)
          );
        }
        if (single.response.status === 403 || single.response.status === 451) {
          await this.noteFreeTierRefusal(input, single.response, log);
        }
        if (single.response.status === 400) {
          let bodyText: string | null = null;
          try {
            bodyText = await single.response.clone().text();
          } catch {
            log?.debug?.("OPENCODE", "body read failed on direct account");
          }
          if (bodyText !== null) {
            if (isEmptyUpstreamRejection(400, bodyText)) {
              const chatcmplId = extractChatcmplId(bodyText);
              log?.warn?.(
                "OPENCODE",
                `${cid}upstream empty rejection on direct account (${chatcmplId}), retrying once…`
              );
              return this.finalizeForcedStream(
                input,
                this.normalizeMuseSparkResponse(input, await guardStall(await super.execute(input)))
              );
            }
            log?.debug?.(
              "OPENCODE",
              "400 without error field, signature not matched on direct account — observing"
            );
          }
        }
        return this.finalizeForcedStream(input, this.normalizeMuseSparkResponse(input, single));
      }

      // This loop only ever dispatches through super.execute() (the HTTP request
      // path), which always resolves the object-shaped arm of ExecutorExecuteResult
      // — the bare-Response arm belongs to web/scraping executors only (base.ts:290).
      type HttpExecuteResult = Extract<
        Awaited<ReturnType<BaseExecutor["execute"]>>,
        { response: Response }
      >;
      let lastResult: HttpExecuteResult | null = null;
      let lastSharedEgressError: unknown = null;
      const sharedEgressGuardEnabled = isNetworkRotationSharedEgressGuardEnabled();
      // Set once a proxy-less account's network throw reveals the shared
      // egress is down (see NETWORK_ROTATION_SHARED_EGRESS_GUARD below) —
      // subsequent proxy-less accounts this request are skipped without a
      // network call, but proxied accounts (independent egress) are still
      // tried normally.
      let sharedEgressDown = false;
      // Bounded extra attempts for empty upstream rejections: +1 for a single
      // account (retry the same one), none for a multi-account fleet (rotation
      // through the accounts is the retry). Avoids an unbounded loop on a
      // persistently malformed upstream.
      const emptyRejectionBudget = accounts.length === 1 ? 1 : 0;
      // Request-local: geo/transient + 429 no-replay keys, one last resort after a 429.
      const geoTriedProxyKeys = new Set<string>(),
        rateLimitedProxyKeys = new Set<string>(),
        spare = egressPacing.lastResort429(accounts, this, geoTriedProxyKeys, rateLimitedProxyKeys);
      // (PROXY_SKIP_RECENTLY_FAILED, default on): members the provider just refused
      // (received refusal or refused TCP probe) are skipped. =false = plain rotation.
      const skipRecentlyFailed = isProxySkipRecentlyFailedEnabled();
      let directTried = false;
      const stallCounter = { attempts: 0 }; // first-byte stalls: one rotation, then fail fast
      // A response an opt-in branch rotated away from. It stays lastResult (and
      // intact) until a newer attempt replaces it, then its body is cancelled.
      let abandonedResponse: Response | null = null;
      // OPENCODE_USER_BLOCKED_ROTATION: rotations spent on user_blocked refusals (max 1).
      let userBlockedRotations = 0;
      // Consecutive transient failures (5xx / empty 400) and the pause time spent on
      // them this request — only acted on when OPENCODE_TRANSIENT_FAILOVER_BACKOFF is on.
      let transientStreak = 0;
      let transientPausedMs = 0;
      let burstStreak = 0,
        parked = false;
      const requestPacing = egressPacing.initEgressPacingForRequest(); // Off by default.
      // Pool re-selection cell: a member the 429 arm asked the pool for, served
      // at the next dispatch instead of the account's own proxy (or, for a
      // proxy-less account, instead of inheriting the ambient member). Written
      // once per 429 on the plain-rotation path, read at every dispatch below.
      let reselectedProxy: ScopedAccount["proxy"] | undefined;
      // served-account changes (effective-change counting) live in the leaf tracker.
      const noteServedAccount = createServedAccountTracker();
      // Cumulative wait imposed before dispatch (egress pacing + park),
      // published as snapshots to the ALS capture sink. A stopwatch, never a
      // key attribute — no egress-key read here.
      const addedWait = { ms: 0, causes: new Set<AddedWaitCause>() };
      const publishAddedWait = (): void => noteAddedWait(addedWait.ms, addedWait.causes);
      // Single park counter (wrapper alone, no hook in the park
      // module). parkWithHeartbeat calls driver.sleep per elapsed step in both
      // stream (closure start()) and non-stream paths, so wrapping this one
      // sleep counts every parked step exactly once. Monotone += only.
      const parkSleepCounting = async (
        ms: number,
        signal?: AbortSignal | null
      ): Promise<boolean> => {
        const elapsed = await this.parkSleep(ms, signal);
        if (elapsed) {
          addedWait.ms += ms;
          addedWait.causes.add("park");
          publishAddedWait();
        }
        return elapsed;
      };
      const appliedEgress = egressPacing.createAppliedEgressTracker(
        this.buildUrl(String(input.model ?? ""), Boolean(input.stream)),
        resolveProxyForRequest
      );
      const { readAppliedKey, keyOfMember, noteRefused } = appliedEgress;

      for (let attempt = 0; attempt < accounts.length + emptyRejectionBudget; attempt++) {
        appliedEgress.resetAttempt();
        const isProxiedCandidate = (a: ScopedAccount): boolean => {
          if (a.cooldownUntil > Date.now()) return false;
          // Without any geo evidence this pass, every cooldown-ready account
          // stays eligible (preserves the plain round-robin first pick).
          const memberKey = keyOfMember(a);
          if (a.proxy === null) {
            if (skipRecentlyFailed && isProxyAvoided(memberKey)) return false;
            return !directTried || geoTriedProxyKeys.size === 0;
          }
          if (skipRecentlyFailed && isProxyAvoided(memberKey)) return false;
          const k = proxyKeyOf(a.proxy);
          return k !== null && !geoTriedProxyKeys.has(k) && !rateLimitedProxyKeys.has(k);
        };
        let account = this.pickAccountWith(accounts, isProxiedCandidate, keyOfMember);
        if (attributionOn) {
          const nowMs = Date.now();
          for (const a of accounts) {
            if (a.cooldownUntil > nowMs) {
              const prev = skippedCooldown.get(a.fingerprint);
              if (prev === undefined || a.cooldownUntil > prev) {
                skippedCooldown.set(a.fingerprint, a.cooldownUntil);
              }
            }
          }
          recordRotationSnapshot(
            String(input.credentials?.connectionId ?? ""),
            this.snapshotEntries(accounts, nowMs)
          );
        }
        // Last resort: one direct attempt (distinct egress) once no proxied account is a candidate.
        if (!isProxiedCandidate(account) && !directTried && geoTriedProxyKeys.size > 0) {
          const direct = accounts.find((a) => a.proxy === null && a.cooldownUntil <= Date.now());
          if (direct) account = direct;
        }
        const lastStatus = lastResult !== null ? lastResult.response.status : null;
        const lastResort = spare.take(lastStatus, account, isProxiedCandidate);
        account = lastResort ?? account;
        const lastWasGeo = lastStatus === 403 || lastStatus === 451;
        const lastWasTransient = lastStatus !== null && lastStatus >= 500 && lastStatus < 600;
        const isMonoRetryOwed = accounts.length === 1 && lastWasTransient;
        if (
          !isMonoRetryOwed &&
          lastResult !== null &&
          geoTriedProxyKeys.size + rateLimitedProxyKeys.size > 0 &&
          !(account === lastResort || isProxiedCandidate(account)) &&
          !(account.proxy === null && !directTried)
        ) {
          // Geo/transient exhaustion → surface as-is, no success mark.
          // Any other last status (e.g. 429 after 403s) → skip without a call.
          if (lastWasGeo || lastWasTransient) break;
          continue;
        }
        // Commit the last-resort direct attempt so a later exclusion breaks
        // instead of retrying it. Set here (not at pick time) so the guard
        // above still lets this committed attempt through.
        if (account.proxy === null && geoTriedProxyKeys.size > 0) directTried = true;
        const masked = maskAccountId(account.fingerprint);

        if (sharedEgressGuardEnabled && sharedEgressDown && !account.proxy) {
          log?.warn?.(
            "OPENCODE",
            `${cid}skipping account ${masked} (no dedicated proxy, shared egress already down this request)`
          );
          continue;
        }

        // Opt-in (#13615): after repeated transient failures, release the failed body
        // and wait (bounded) before the next account; a client abort stops the loop.
        const pauseMs = transientRetryDelayMs(transientStreak, transientPausedMs);
        if (pauseMs > 0 && lastResult !== null && isOpencodeTransientFailoverBackoffEnabled()) {
          lastResult = { ...lastResult, response: releaseResponseBody(lastResult.response) };
          transientPausedMs += pauseMs;
          log?.info?.(
            "OPENCODE",
            `${cid}${transientStreak} transient failures, pausing ${pauseMs}ms`
          );
          if (!(await this.transientPauseSleep(pauseMs, input.signal))) break;
        }

        // #5217 (Gap 2): promoted debug→info so the per-request account/proxy
        // rotation selection is visible in the Console log view at the default
        // APP_LOG_LEVEL=info (users could not see which account/proxy was used).
        // Token stays masked — never log the full account id.
        log?.info?.(
          "OPENCODE",
          `${cid}dispatch via account ${masked} (idx ${attempt + 1}/${accounts.length})` +
            (account.proxy
              ? ` through proxy ${account.proxy.host}:${account.proxy.port}`
              : " direct")
        );
        // Rotation attribution: publish the masked serving id for the proxy log
        // (multi-account anonymous rotation only — a lone direct account stays
        // silent so the configured connection id keeps its meaning).
        if (attributionOn && (accounts.length > 1 || account.fingerprint !== "")) {
          noteRotationAccount(masked);
        }
        // effective-change counting on the masked id (the raw
        // fingerprint never reaches the log, just the counter).
        noteServedAccount(masked);

        // Pin egress to this account's proxy for the whole BaseExecutor dispatch
        // (incl. its intra-URL 429 retries). skipUpstreamRetry lets THIS loop own
        // the cross-account 429 fallback instead of BaseExecutor's same-key retry.
        // Wall-clock around the paced acquire (sync repick included —
        // µs against waits in seconds). Time endured in queue counts on every
        // outcome: slot granted, fail-open null, or repick.
        const throttleStart = Date.now();
        const paced = await egressPacing.startPacedDispatch(
          requestPacing,
          account,
          isProxiedCandidate,
          () => this.pickAccountWith(accounts, isProxiedCandidate, keyOfMember),
          input.signal,
          readAppliedKey
        );
        const egressRelease = paced.release;
        account = paced.account;
        const throttleDelta = Math.max(0, Date.now() - throttleStart);
        if (throttleDelta > 0) {
          addedWait.ms += throttleDelta;
          addedWait.causes.add("throttle");
          publishAddedWait();
        }
        appliedEgress.rememberServed(account); // Served (post repick); the attempt egress label reads it here.
        const egress = egressPacing.egressLabel(account, readAppliedKey);
        let result: HttpExecuteResult;
        try {
          const { outcome, waitMs } = await headersWaitDispatch(
            // opt-in bound on the guarded dispatch (stall guard inside the race)
            headersWait,
            account,
            accounts,
            isProxiedCandidate,
            (attemptSignal) =>
              (async () =>
                guardStall(
                  await runWithProxyContext(account.proxy ?? reselectedProxy, () =>
                    super.execute({
                      ...input,
                      skipUpstreamRetry: true,
                      signal: attemptSignal ?? input.signal,
                    })
                  )
                ) as Promise<HttpExecuteResult>)(),
            input.signal
          );
          if (outcome.kind !== "ok") {
            if (outcome.kind === "aborted")
              egressPacing.throwPacedError(egressRelease, outcome.reason);
            egressPacing.settleStalledDispatch(egressRelease, account, {
              tried: geoTriedProxyKeys,
              stalled: headersWait.spent,
              cooldown: markCooldown,
              markDirect: () => (directTried = true),
              slow: { account, enabled: skipRecentlyFailed, egress: appliedEgress },
            }); // same settle as the stall arm
            log?.warn?.(
              "OPENCODE",
              `${cid}no response headers within ${waitMs}ms on account ${masked}, rotating to next… ${egress}`
            );
            continue;
          }
          result = appliedEgress.noteServed(account, outcome.result, waitMs, skipRecentlyFailed);
        } catch (err) {
          if (headersWait.policy.windowMs > 0 && input.signal?.aborted)
            egressPacing.throwPacedError(egressRelease, err); // client abort never rotates, slot released
          const reason = err instanceof Error ? err.message : String(err);
          // Stall guard: headers arrived, so the egress works — never a shared-egress
          // outage; proxied and proxy-less accounts rotate alike. A client abort never rotates.
          if (stallWindowMs > 0 && (isResponsesFirstByteTimeout(err) || input.signal?.aborted)) {
            if (input.signal?.aborted) egressPacing.throwPacedError(egressRelease, err);
            const rotate = egressPacing.settleStalledDispatch(egressRelease, account, {
              tried: geoTriedProxyKeys,
              stalled: stallCounter,
              cooldown: markCooldown,
              markDirect: () => (directTried = true),
            });
            log?.warn?.(
              "OPENCODE",
              `${cid}stream stalled on account ${masked}, ${rotate ? "rotating…" : "not rotating again"} (${reason}) ${egress}`
            );
            if (!rotate) egressPacing.throwPacedError(egressRelease, err);
            continue;
          }
          transientStreak = 0;
          // A network exception (timeout, connection refused/reset) is only
          // account-scoped when this account has its OWN egress (a configured
          // proxy) — that's the case a dead/unreachable proxy justifies rotating
          // away from. Without a proxy, accounts share the same network egress:
          // the failure isn't attributable to this account. Never swallowed
          // silently either way: logged before rotating, skipping, or rethrowing.
          if (!isNetworkErrorRotatable(account)) {
            if (sharedEgressGuardEnabled) {
              markCooldown(account);
              sharedEgressDown = true;
              lastSharedEgressError = err;
              log?.warn?.(
                "OPENCODE",
                `${cid}network error on account ${masked} (no dedicated proxy, shared egress), cooldown — trying next… (${reason}) ${egress}`
              );
              egressPacing.releasePacingSlot(egressRelease);
              continue;
            }
            log?.warn?.(
              "OPENCODE",
              `${cid}network error on account ${masked} (no dedicated proxy, shared egress) — not rotating (${reason}) ${egress}`
            );
            egressPacing.throwPacedError(egressRelease, err);
          }
          markCooldown(account);
          log?.warn?.(
            "OPENCODE",
            `${cid}network error on account ${masked}, rotating to next… (${reason}) ${egress}`
          );
          egressPacing.releasePacingSlot(egressRelease);
          continue;
        }
        discardResponseBody(abandonedResponse);
        abandonedResponse = null;
        lastResult = result;
        const priorTransientStreak = transientStreak;
        transientStreak = 0;
        if (result.response.status !== 429) burstStreak = 0;

        try {
          const status = result.response.status;
          if (status === 429) {
            markCooldown(account);
            const rateKey = proxyKeyOf(account.proxy);
            if (rateKey !== null) rateLimitedProxyKeys.add(rateKey);
            const setAsideMs = appliedEgress.noteRefused(account, skipRecentlyFailed);
            appliedEgress.rememberServed(account);
            // Opt-in (#13657): a 429 that names a real rate limit stops the wave and
            // the real upstream 429 is returned untouched (body, Retry-After, quota
            // headers), so provider error rules still apply. Flag off → rotate.
            // The settle releases the slot exactly once; a burst parks the
            // request once its slot budget is spent.
            const arm = await egressPacing.settle429Arm(
              egressRelease,
              requestPacing,
              result.response,
              isOpencodeRateLimited429EarlyStopEnabled
            );
            egressPacing.log429Outcome(log, cid, arm, masked, setAsideMs, egress);
            if (arm === "stop") {
              if (attributionOn && skippedCooldown.size > 0) {
                this.logSkippedCooldownAccounts(log, cid, skippedCooldown);
              }
              return result;
            }
            if (arm === "park") {
              // Slot budget spent: join the park-and-replay path below
              // instead of surfacing the last 429. The park flag can still
              // veto (fail-closed: plain break).
              if (!isOpencodeParkAndResumeEnabled()) break;
              burstStreak = Math.max(burstStreak + 1, BURST_PARK_THRESHOLD);
            } else {
              burstStreak += 1;
            }
            if (!parked && isOpencodeParkAndResumeEnabled()) {
              const marker = await readPoolStrainMarker();
              const setAsideWaitMs = setAsideParkWaitMs(accounts.map((a) => keyOfMember(a)));
              if (burstStreak >= BURST_PARK_THRESHOLD || marker.fresh || setAsideWaitMs !== null) {
                parked = true;
                log?.warn?.(
                  "OPENCODE",
                  `${cid}burstStreak=${burstStreak} freshD2=${marker.fresh} park`
                );
                // local monotone park measure (Date.now diff, integer ms).
                const parkStartMs = Date.now();
                const p = await runParkAndReplay(
                  {
                    execute: (i: ExecuteInput) =>
                      super.execute(i) as Promise<ExecutorExecuteResult & { response: Response }>,
                    markSuccess: (a: ScopedAccount) => markSuccess(a),
                    sleep: parkSleepCounting,
                    accounts,
                    replayKeyOfMember: keyOfMember,
                  },
                  input,
                  Math.min(
                    setAsideWaitMs ?? Number.POSITIVE_INFINITY,
                    parkWaitMs(marker.fresh ? marker.ttlLeftMs : null)
                  ),
                  result,
                  log,
                  cid
                );
                noteParkWait(Date.now() - parkStartMs);
                if (p && p !== result) {
                  if (attributionOn && skippedCooldown.size > 0) {
                    this.logSkippedCooldownAccounts(log, cid, skippedCooldown);
                  }
                  noteReplayed();
                  return this.normalizeMuseSparkResponse(input, p);
                }
                if (p) {
                  discardResponseBody(abandonedResponse);
                  if (attributionOn && skippedCooldown.size > 0) {
                    this.logSkippedCooldownAccounts(log, cid, skippedCooldown);
                  }
                  noteStoredFallback();
                  return this.normalizeMuseSparkResponse(input, result);
                }
              }
            }
            // Pool re-selection (opt-in, flag read once per request above): the
            // account that just took this 429 has no proxy of its own, so the
            // attempt egressed through the ambient pool member — and this
            // provider buckets quota by egress address. Ask the pool for
            // another member for the next attempt instead of retrying the
            // refused address. Orders, never excludes: a null resolver result
            // (exhausted or held back) keeps the current behavior. Placed
            // after every stop/park exit above so a wave-ending verdict never
            // consumes a rotation step.
            if (poolReselect && account.proxy === null) {
              const next = await poolReselect().catch(() => null);
              if (
                next !== null &&
                typeof next === "object" &&
                typeof (next as { host?: unknown }).host === "string" &&
                typeof (next as { port?: unknown }).port === "number" &&
                poolReselectKeyOf(next) !== lastPoolKey
              ) {
                reselectedProxy = next as ScopedAccount["proxy"];
                lastPoolKey = poolReselectKeyOf(next);
                log?.warn?.(
                  "OPENCODE",
                  `${cid}pool re-selected egress for account ${masked} after 429, retrying on another member… ${egressPacing.egressLabel({ proxy: next as ScopedAccount["proxy"], fingerprint: account.fingerprint })}`
                );
              }
            }
            continue;
          }

          if (isRetriableUpstreamFailure(status)) {
            const key = proxyKeyOf(account.proxy);
            if (key !== null) geoTriedProxyKeys.add(key);
            else directTried = true;
            transientStreak = priorTransientStreak + 1;
            log?.warn?.(
              "OPENCODE",
              `${cid}transient upstream ${status} on account ${masked}, rotating to next… ${egress}`
            );
            // Deliberately a separate branch from the 400-empty arm below,
            // not one merged `if`: this arm never touches the body, the 400
            // arm must clone-read it. Both share the predicate + tried-set.
            // Single proxied account: one retry via the existing budget (a
            // proxy-less single account takes the fast path, never the loop).
            // Transient is not deterministic like geo: upstream may recover.
            // No 0-retry guard here (it stays geo-only).
            continue;
          }

          if (status === 403 || status === 451) {
            let bodyText: string | null = null;
            try {
              bodyText = await result.response.clone().text();
            } catch {
              log?.debug?.("OPENCODE", "body read failed on geo-block check");
            }
            if (bodyText !== null && isOpencodeGeoBlocked(status, bodyText)) {
              const key = proxyKeyOf(account.proxy);
              if (key !== null) geoTriedProxyKeys.add(key);
              else directTried = true;
              const setAsideMs = noteRefused(account, skipRecentlyFailed, "geo_blocked");
              egressPacing.logRefusedOutcome(log, cid, masked, setAsideMs, "geo-blocked", egress);
              // Single account with a proxy: 0 retries (same egress = dead latency).
              // (The fast path above already covers single-without-proxy; here length===1 WITH proxy.)
              if (accounts.length === 1) {
                if (attributionOn && skippedCooldown.size > 0) {
                  this.logSkippedCooldownAccounts(log, cid, skippedCooldown);
                }
                return result;
              }
              continue;
            }
            // Opt-in (#13498): an upstream user_blocked refusal (403 or 451, same
            // predicate) cools the refused account down, joins the tried-set and
            // rotates at most once per request. Never a success mark. Flag off →
            // falls through to the unchanged path below.
            if (
              bodyText !== null &&
              isOpencodeUserBlocked(status, bodyText) &&
              isOpencodeUserBlockedRotationEnabled()
            ) {
              const key = proxyKeyOf(account.proxy);
              if (key !== null) geoTriedProxyKeys.add(key);
              else directTried = true;
              markCooldown(account);
              const rotate = userBlockedRotations === 0 && accounts.length > 1;
              log?.warn?.(
                "OPENCODE",
                `${cid}user_blocked ${status} on account ${masked}, ${rotate ? "rotating to next account once…" : "returning the refusal"} ${egress}`
              );
              if (!rotate) {
                if (attributionOn && skippedCooldown.size > 0) {
                  this.logSkippedCooldownAccounts(log, cid, skippedCooldown);
                }
                return result;
              }
              userBlockedRotations++;
              abandonedResponse = result.response;
              continue;
            }
            // Free-tier refusal: upstream rejected the REQUEST (client identity or
            // request shape), not this account. Handled in opencodeFreeTierRetry.ts
            // (one bounded retry with observed tools appended, then unchanged return).
            if (bodyText !== null && isOwnToolsRetryableRefusal(status, bodyText)) {
              noteFreeTierOutcome(attemptFor(input.body), {
                ok: false,
                status,
                bodyText,
              });
              if (attributionOn && skippedCooldown.size > 0) {
                this.logSkippedCooldownAccounts(log, cid, skippedCooldown);
              }
              return await handleLoopFreeTierRefusal(
                (retried) =>
                  this.finalizeForcedStream(input, this.normalizeMuseSparkResponse(input, retried)),
                input,
                result,
                this.freeTierRetryCtx(input),
                { account, masked, proxyKey: proxyKeyOf(account.proxy) ?? "direct" },
                log,
                cid,
                {
                  dispatch: (retryInput) =>
                    runWithProxyContext(account.proxy, () =>
                      super.execute({ ...retryInput, skipUpstreamRetry: true })
                    ) as Promise<HttpExecuteResult>,
                  noteServed: (a) => noteResponseServed(a as typeof account),
                }
              );
            }
          }

          // Empty upstream rejection (malformed 400: no error field, no real
          // content, finish_reason null — see isEmptyUpstreamRejection). Rotate/
          // retry instead of propagating it as a fatal success: the observed
          // envelope was marking subagent sessions as failed. Read the body ONLY
          // for a 400 (never a 200/streaming — that would buffer the good path);
          // classify, log, and continue. Neitheries markCooldown nor markSuccess:
          // the failure is upstream's, not this account's.
          if (status === 400) {
            let bodyText: string | null = null;
            try {
              bodyText = await result.response.clone().text();
            } catch {
              log?.debug?.("OPENCODE", "body read failed on empty rejection check");
            }
            if (bodyText !== null && isRetriableUpstreamFailure(400, bodyText)) {
              const chatcmplId = extractChatcmplId(bodyText);
              transientStreak = priorTransientStreak + 1;
              log?.warn?.(
                "OPENCODE",
                `${cid}upstream empty rejection on account ${masked} (${chatcmplId}), rotating to next… ${egress}`
              );
              continue;
            }
            // A 400 carrying a real error (or non-empty content): propagate
            // immediately, untouched — same as before this change.
            markOutcome(account, result.response);
            if (attributionOn && skippedCooldown.size > 0) {
              this.logSkippedCooldownAccounts(log, cid, skippedCooldown);
            }
            return result;
          }

          egressPacing.observePacingSuccess(requestPacing, result.response.ok);
          markOutcome(account, result.response);
          if (attributionOn && skippedCooldown.size > 0) {
            this.logSkippedCooldownAccounts(log, cid, skippedCooldown);
          }
          return this.finalizeForcedStream(input, this.normalizeMuseSparkResponse(input, result));
        } finally {
          // Single release point for every post-dispatch arm (5xx, 403/451,
          // free-tier, 429, 400, success): the released-guard makes the 429
          // internal release a harmless no-op.
          egressPacing.releasePacingSlot(egressRelease);
        }
      }

      // The loop exhausted without a result. If it's because every remaining
      // proxy-less account was skipped once the shared egress was known down
      // (rather than actually tried), propagate that original throw — an
      // extra direct call here would just be a second doomed attempt against
      // the same dead path, which is exactly the latency this guard exists
      // to avoid (see NETWORK_ROTATION_SHARED_EGRESS_GUARD).
      if (sharedEgressDown && !lastResult && lastSharedEgressError !== null) {
        throw lastSharedEgressError;
      }

      // All accounts returned 429 (or errored) — surface the last response.
      if (attributionOn && skippedCooldown.size > 0) {
        this.logSkippedCooldownAccounts(log, cid, skippedCooldown);
      }
      return this.finalizeForcedStream(
        input,
        this.normalizeMuseSparkResponse(
          input,
          lastResult ?? (await guardStall(await super.execute(input)))
        )
      );
    } finally {
      this._requestFormat = null;
    }
  }

  buildUrl(
    model: string,
    stream: boolean,
    urlIndex = 0,
    credentials: ProviderCredentials | null = null
  ) {
    void urlIndex;
    void credentials;

    const base =
      Boolean(model) && isGatedFreeTierRequest(this._surface(), this.provider, model)
        ? FREE_TIER_INFERENCE_BASE_URL
        : this.config.baseUrl;
    switch (this._requestFormat) {
      case "claude":
        return `${base}/messages`;
      case "openai-responses":
        return `${base}/responses`;
      case "gemini":
        return `${base}/models/${model}:${stream ? "streamGenerateContent?alt=sse" : "generateContent"}`;
      default:
        return `${base}/chat/completions`;
    }
  }

  /**
   * #12633: OpenCode Zen's `/v1/responses` endpoint (reached when
   * `_requestFormat === "openai-responses"`, e.g. Muse Spark Contributor
   * models) requires `x-api-key`, not `Authorization: Bearer` — unlike the
   * default `/chat/completions` endpoint on the same host, which accepts
   * Bearer. Scoped by baseUrl (not provider id/alias) so this only applies to
   * the main Zen host (`opencode` / `opencode-zen`, both `https://opencode.ai/zen/v1`)
   * and never to opencode-go, which serves Responses-format models from a
   * different upstream (`https://opencode.ai/zen/go/v1`) that expects Bearer.
   */
  private usesZenApiKeyAuth(): boolean {
    return this._requestFormat === "openai-responses" && this.config?.baseUrl === ZEN_BASE_URL;
  }

  buildHeaders(
    credentials: ProviderCredentials | null,
    stream = true,
    clientHeaders?: Record<string, string> | null,
    model?: string,
    _health?: Record<string, unknown>,
    body?: unknown
  ) {
    const headers: Record<string, string> = { "Content-Type": "application/json" };
    // #8467: honor Extra API Keys rotation via BaseExecutor.resolveEffectiveKey.
    // Fall back to accessToken only when no apiKey/extras resolve to a key.
    const key = credentials
      ? this.resolveEffectiveKey(credentials) || credentials.accessToken
      : undefined;

    // The free tier only answers streamed requests (measured 2026-09-17: a non-streamed
    // body answers 403 FreeTierError), so a JSON client is served by streaming upstream and
    // rebuilding the JSON body from the event stream — the path chatCore already takes for
    // any buffered event-stream response. Announcing the stream here keeps that buffering an
    // expected outcome rather than a warning.
    const gatedScope =
      Boolean(model) && isGatedFreeTierRequest(this._surface(), this.provider, model);

    if (key) {
      if (this._requestFormat === "claude" || this.usesZenApiKeyAuth()) {
        headers["x-api-key"] = key;
      } else {
        headers["Authorization"] = `Bearer ${key}`;
      }
    }

    if (this._requestFormat === "claude") {
      headers["anthropic-version"] = "2023-06-01";
    }
    if (stream || gatedScope) {
      headers["Accept"] = "text/event-stream";
    }

    // Synthesize OpenCode CLI identity headers by default so Cloudflare in front of
    // opencode.ai/zen doesn't 429 VPS requests lacking CLI identity. Opt-out via
    // OPENCODE_SYNTHESIZE_CLI_HEADERS=false. Client-supplied headers always win;
    // User-Agent is replaced with the CLI UA unless the client already sends one that
    // looks like the OpenCode CLI. Default values match 9router's proven defaults.
    // #16571: the OpenCode v2 client fingerprint is opt-in (default off: identity unchanged).
    const v2Fingerprint = isOpencodeV2ClientFingerprintEnabled();
    const cliDefaults = resolveOpencodeCliDefaults(
      this.config?.id || this.provider || "opencode",
      gatedScope,
      v2Fingerprint
    );

    this._clientSession = clientSuppliedOpencodeSession(clientHeaders, body);
    if (clientHeaders || cliDefaults) {
      forwardOpencodeClientHeaders(headers, clientHeaders ?? {}, {
        synthesizeRequestId: true,
        cliDefaults,
        keepAgentUserAgent: this._surface() === "go" && !gatedScope, // #15311
        sessionBody: projectOpencodeSessionBody(body),
        reencodeSession: gatedScope,
        v2Fingerprint,
      });
    }

    // The Muse Responses workaround that forced a UUID session here is gone: the shape it
    // produced is exactly what the upstream now refuses, and the canonical session it used
    // to overwrite is accepted on that surface (measured 2026-09-17, 200 on
    // muse-spark-1.3-contributor-free via /v1/responses).

    return headers;
  }

  /**
   * OpenCode's free DeepSeek V4 Flash endpoint accepts json_object but
   * rejects json_schema response_format with HTTP 400. Preserve the schema
   * as an instruction and downgrade only this proven-incompatible route to
   * json_object so callers still receive structured JSON.
   */
  private applyDeepSeekJsonSchemaFallback<T>(model: string, body: T): T {
    if (
      (model !== "deepseek-v4-flash-free" && model !== "deepseek-v4.1-flash-free") ||
      (this.provider !== "opencode" && this.provider !== "opencode-zen")
    ) {
      return body;
    }

    if (!body || typeof body !== "object" || Array.isArray(body)) {
      return body;
    }

    const record = body as Record<string, unknown>;
    const responseFormat = record.response_format as
      | {
          type?: string;
          json_schema?: {
            schema?: unknown;
          };
        }
      | undefined;

    if (responseFormat?.type !== "json_schema" || !responseFormat.json_schema?.schema) {
      return body;
    }

    const schemaJson = JSON.stringify(responseFormat.json_schema.schema, null, 2);

    const prompt =
      "You must respond with valid JSON that strictly follows " +
      "this JSON schema:\\n```json\\n" +
      schemaJson +
      "\\n```\\nRespond ONLY with the JSON object, no other text and no markdown code fences.";

    const messages: Array<Record<string, unknown>> = Array.isArray(record.messages)
      ? (record.messages as Array<Record<string, unknown>>).map((message) => ({ ...message }))
      : [];

    const systemMessage = messages.find((message) => message.role === "system");

    if (systemMessage) {
      if (typeof systemMessage.content === "string") {
        systemMessage.content = `${systemMessage.content}\\n\\n${prompt}`;
      } else if (Array.isArray(systemMessage.content)) {
        systemMessage.content.push({
          type: "text",
          text: `\\n\\n${prompt}`,
        });
      }
    } else {
      messages.unshift({
        role: "system",
        content: prompt,
      });
    }

    return {
      ...record,
      messages,
      response_format: {
        type: "json_object",
      },
    } as T;
  }

  transformRequest(
    model: string,
    body: any,
    stream: boolean,
    credentials: ProviderCredentials
  ): any {
    let modifiedBody = super.transformRequest(model, body, stream, credentials);
    modifiedBody = this.applyDeepSeekJsonSchemaFallback(model, modifiedBody);
    // Free-tier request contract (see opencodeFreeTierContract.ts): streaming plus a
    // non-empty tools array, in the shape of the surface this model is served on. Paid
    // models on the same host are not gated and stay untouched.
    const prepared = prepareFreeTierRequest(
      modifiedBody,
      this._requestFormat ?? resolveOpencodeTargetFormat(this.provider, model),
      this._surface(),
      this.provider,
      model,
      this._clientSession,
      body,
      isOpencodeV2ClientFingerprintEnabled()
    );
    modifiedBody = prepared.body;
    // OpenCode's upstream 400s a request when a single enum property carries
    // more than 250 values or 15000 combined characters (VSCode-shaped caller
    // tools hit this). Cap oversized enums on every surface before dispatch —
    // covers caller tools and contract-borrowed declarations alike.
    if (
      modifiedBody &&
      typeof modifiedBody === "object" &&
      !Array.isArray(modifiedBody) &&
      Array.isArray((modifiedBody as Record<string, unknown>).tools)
    ) {
      trimOversizedToolEnums((modifiedBody as Record<string, unknown>).tools);
    }
    // 9router#1442: OpenCode upstreams (e.g. kimi-k2.6 via opencode-go) return
    // 400 "Extra inputs are not permitted, field: 'client_metadata'" — an
    // OpenAI-Codex/Claude-CLI passthrough field with no equivalent here. The
    // DefaultExecutor strip only covers cerebras/mistral, and OpencodeExecutor
    // extends BaseExecutor directly, so nothing removed it on this path.
    if (
      modifiedBody &&
      typeof modifiedBody === "object" &&
      !Array.isArray(modifiedBody) &&
      Object.prototype.hasOwnProperty.call(modifiedBody, "client_metadata")
    ) {
      delete (modifiedBody as Record<string, unknown>).client_metadata;
    }
    if (modifiedBody && typeof modifiedBody === "object" && !Array.isArray(modifiedBody)) {
      const mb = modifiedBody as Record<string, unknown>;
      mb.model = stripOpencodeModelPrefix(mb.model); // see providerModels.ts
      // OpenCode accepts stream_options only on streaming Chat Completions (#13699).
      const format = this._requestFormat ?? resolveOpencodeTargetFormat(this.provider, model);
      if (format !== "openai" || mb.stream !== true) {
        delete mb.stream_options;
      }
      const parsed = parseEffortLevel(model);
      if (parsed) {
        const deepseekFamily =
          parsed.baseModel === "deepseek-v4-pro" || parsed.baseModel === "deepseek-v4-flash";
        if (deepseekFamily) {
          // DeepSeek via opencode-go proxies the native DeepSeek contract, which
          // accepts a flat reasoning_effort field (#4647).
          mb.model = parsed.baseModel;
          if (mb.reasoning_effort === undefined) {
            mb.reasoning_effort = parsed.effort;
          }
        }
        // #10788: every other family's ONLY native effort mechanism is the
        // -<tier> suffix in the model id itself (the ids `opencode models
        // opencode-go --verbose` lists). The opencode-go ChatCompletionRequest
        // carries no flat reasoning_effort field, so rewriting to the base id
        // silently dropped the tier — forward the aliased id verbatim instead.
      }
    }
    // #1543 / upstream PR #1099: thinking-mode upstreams routed through OpenCode
    // (DeepSeek V4 Flash, Kimi, MiniMax, ...) require reasoning_content echoed
    // back on assistant messages, or they 400 with "reasoning_content must be
    // passed back". OpenAI clients drop it across turns, so we inject a
    // placeholder for the affected model families.
    if (isThinkingMessageModel(model)) {
      modifiedBody = injectReasoningContentForThinkingModel(modifiedBody);
    }
    const toolFormat = this._requestFormat ?? resolveOpencodeTargetFormat(this.provider, model);
    applyOpencodeToolNameLengthAliases(this.provider, modifiedBody, toolFormat);
    return modifiedBody;
  }
}