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

6.9 KB
Raw Blame
/**
 * Classify helpers for executeTarget's retry loop.
 * Lift-as-is from combo.ts #8375 / #2101 / #4279; stop cleanup uses injected deps.
 *
 * @internal — not part of the public combo.ts barrel.
 */
import { isInputBoundRequestFailure } from "./comboPredicates.ts";
import { comboTargetDecision } from "./statusDecisionTable.ts";
import {
  errorResponse,
  errorResponseWithComboDiagnostics,
  isContentPolicyRefusalComboStopEnabled,
} from "../../utils/error.ts";
import { isContentPolicyRefusal } from "../../utils/contentPolicyError.ts";
import { buildRedactedSummary } from "./comboErrorAggregation.ts";
import type { ComboDiagnostics } from "../../utils/error.ts";
import { formatExhaustedConnectionKey } from "./comboDiagFormat.ts";
import { collectQuotaWindowExclusions } from "./quotaSkipDiagnostics.ts";
import { getComboTrace, summarizeSkippedTargets } from "./decisionTrace.ts";
import { buildRecoveryHint } from "./pinRecovery.ts";
import type { AttemptLoopDeps, AttemptLoopState } from "./attemptLoopTypes.ts";
import type { ResolvedComboTarget } from "./types.ts";
import {
  protectedPriorityStopStatus,
  type ProtectedPriorityStopCause,
} from "./protectedPriorityStopStatus.ts";
import type { ResponseQualityResult } from "./validateQuality.ts";

/**
 * Terminal diagnostics attached to combo-level errors. Shared by the priority
 * target loop and the set-retry loop so both emit the same trace shape.
 */
export function buildComboDiag(
  state: AttemptLoopState,
  traceInvocationId: string,
  terminalReason: string,
  retryAfterSeconds?: number
): ComboDiagnostics {
  return {
    poolSize: state.orderedTargets.length,
    attempted: state.recordedAttempts,
    excluded: [
      ...[...state.exhaustedProviders].map((p) => ({ provider: p, reason: "exhausted" })),
      ...[...state.exhaustedConnections].map((c) => formatExhaustedConnectionKey(String(c))),
      ...(terminalReason === "all_targets_skipped"
        ? collectQuotaWindowExclusions(state.orderedTargets)
        : []),
    ],
    attemptOrder: state.comboAttemptOrder,
    terminalReason,
    recovery: buildRecoveryHint(terminalReason, retryAfterSeconds),
    // #12659: surface per-target skip reasons (e.g. persisted_cooldown) that
    // `excluded` never captures — only worth the trace lookup on the
    // diagnostic-heavy terminal reason.
    skippedTargets:
      terminalReason === "all_targets_skipped"
        ? summarizeSkippedTargets(getComboTrace(traceInvocationId)).map((g) => ({
            reason: g.reason,
            targets: g.targets,
          }))
        : undefined,
  };
}

/** Preserve prior attempt metadata without exposing upstream bodies or changing stop policy. */
export function buildProtectedPriorityStopResponse(opts: {
  state: AttemptLoopState;
  traceInvocationId: string;
  message: string;
  cause?: ProtectedPriorityStopCause;
}): Response {
  const previous = buildRedactedSummary(opts.state.comboErrors);
  return errorResponseWithComboDiagnostics(
    protectedPriorityStopStatus(opts.cause),
    previous ? `${opts.message}; earlier attempts: ${previous}` : opts.message,
    buildComboDiag(opts.state, opts.traceInvocationId, "protected_priority_stop")
  );
}

/** Record a target stop, returning a terminal response only for protected targets. */
export function stopProtectedPriorityTarget(opts: {
  protectedPriorityTarget: boolean;
  state: AttemptLoopState;
  deps: Pick<AttemptLoopDeps, "combo" | "log" | "clearStaleLKGP" | "traceInvocationId">;
  target: ResolvedComboTarget;
  message: string;
  cause?: ProtectedPriorityStopCause;
}): { ok: false; response: Response } | null {
  const { state, deps, target } = opts;
  state.observeFailure(false, target.executionKey);
  deps.clearStaleLKGP(
    deps.combo.name,
    target.executionKey,
    deps.combo.id,
    deps.log,
    "COMBO",
    undefined,
    target
  );
  return opts.protectedPriorityTarget
    ? {
        ok: false as const,
        response: buildProtectedPriorityStopResponse({
          state,
          traceInvocationId: deps.traceInvocationId,
          message: opts.message,
          cause: opts.cause,
        }),
      }
    : null;
}

export function remainderIsHomogeneous(
  orderedTargets: { modelStr: string }[],
  index: number,
  modelStr: string
): boolean {
  return orderedTargets.slice(index + 1).every((nextInPool) => nextInPool.modelStr === modelStr);
}

/**
 * Handle a pre-content streaming upstream error: nothing reached the client
 * yet, so re-dispatching the same target cannot duplicate output. Logs and
 * returns true when the caller should retry, false to fall through.
 */
export function handlePreContentStreamRetry(
  quality: ResponseQualityResult,
  retry: number,
  deps: {
    maxRetries: number;
    signal?: { aborted?: boolean } | null;
    log: { info: (tag: string, msg: string) => void };
  },
  modelStr: string
): boolean {
  if (!quality.upstreamFailure?.retryable || retry >= deps.maxRetries || deps.signal?.aborted) {
    return false;
  }
  deps.log.info(
    "COMBO",
    `Retrying ${modelStr} after pre-content streaming upstream error ` +
      `(attempt ${retry + 2}/${deps.maxRetries + 1})`
  );
  return true;
}

/** Protected-priority target whose upstream body failed quality validation. */
export function qualityValidationFailure(quality: ResponseQualityResult): {
  ok: false;
  response: Response;
} {
  const failure = quality.upstreamFailure;
  if (failure && isContentPolicyRefusal(failure)) {
    return {
      ok: false,
      response: errorResponse(failure.status, failure.message || "Upstream request refused", {
        code: failure.code,
        type: failure.type ?? "invalid_request_error",
      }),
    };
  }
  return {
    ok: false,
    response: quality.upstreamFailure
      ? errorResponse(quality.upstreamFailure.status, quality.reason || "Upstream request failed")
      : errorResponse(502, "Upstream response failed quality validation"),
  };
}

export function shouldAbortOnInputBoundFailure(opts: {
  structuredError: unknown;
  remainderIsHomogeneous: boolean;
}): boolean {
  const structured = opts.structuredError as
    { code?: string | null; type?: string | null } | undefined;
  // #15917: stopping the combo on a content-policy refusal — even with different models
  // remaining — instead of routing around the provider's policy is opt-in via
  // CONTENT_POLICY_REFUSAL_COMBO_STOP_ENABLED; off keeps the release routing.
  if (isContentPolicyRefusal(structured) && isContentPolicyRefusalComboStopEnabled()) return true;
  return isInputBoundRequestFailure(structured) && opts.remainderIsHomogeneous;
}

/**
 * #2101 / #4279: body-specific 400 must surface via {ok,response}, not null.
 * The stop set is COMBO_400_STOP_ROWS. Model-scoped, overflow, and parameter
 * 400s advance even when the body is wrapped as invalid_request_error or
 * Bad Request.
 */
export function shouldSurfaceBodySpecific400(opts: {
  status: number;
  errorText: string;
  shouldFallback: boolean;
}): boolean {
  return opts.shouldFallback && comboTargetDecision(opts.status, opts.errorText) === "stop";
}