/**

* Runs model and image fallback chains across provider/model candidates.

*/

import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";

import { TRANSCRIPT_NOT_CONTINUABLE_ERROR_CODE } from "../../packages/agent-core/src/errors.js";

import { sanitizeForLog } from "../../packages/terminal-core/src/ansi.js";

import {

resolveAgentModelFallbackValues,

resolveAgentModelPrimaryValue,

} from "../config/model-input.js";

import type { OpenClawConfig } from "../config/types.openclaw.js";

import { isCronTerminalAbortReasonText } from "../cron/service/execution-errors.js";

import { emitFailoverEvent } from "../infra/diagnostic-events.js";

import { formatErrorMessage, toErrorObject } from "../infra/errors.js";

import { createSubsystemLogger } from "../logging/subsystem.js";

import { normalizePluginsConfig } from "../plugins/config-state.js";

import { getCurrentPluginMetadataSnapshot } from "../plugins/current-plugin-metadata-snapshot.js";

import { resolvePluginControlPlaneFingerprint } from "../plugins/plugin-control-plane-context.js";

import { isPluginProvidersLoadInFlight } from "../plugins/providers.runtime.js";

import {

getActivePluginRegistryWorkspaceDirFromState,

getPluginRegistryState,

} from "../plugins/runtime-state.js";

import { isCommandLaneTaskTimeoutError } from "../process/command-queue.js";

import { createLazyImportLoader } from "../shared/lazy-promise.js";

import { isDefaultAgentRuntimeId } from "./agent-runtime-id.js";

import { normalizeOptionalAgentRuntimeId } from "./agent-runtime-id.js";

import { externalCliDiscoveryForProviders } from "./auth-profiles/external-cli-discovery.js";

import { resolveSubscriptionAuthModeForProfiles } from "./auth-profiles/profile-list.js";

import { hasAnyAuthProfileStoreSource } from "./auth-profiles/source-check.js";

import type { AuthProfileStore } from "./auth-profiles/types.js";

import { isActiveUnusableWindow } from "./auth-profiles/usage-state.js";

import { DEFAULT_MODEL, DEFAULT_PROVIDER } from "./defaults.js";

import { isLikelyContextOverflowError } from "./embedded-agent-helpers/errors.js";

import type { FailoverReason } from "./embedded-agent-helpers/types.js";

import { isOpenClawAbortableWrapper } from "./embedded-agent-runner/run/abortable.js";

import {

FailoverError,

buildFailoverRemediationHint,

buildProviderReauthCommand,

coerceToFailoverError,

describeFailoverError,

isFailoverError,

isNonProviderRuntimeCoordinationError,

} from "./failover-error.js";

import {

shouldAllowCooldownProbeForReason,

shouldPreserveTransientCooldownProbeSlot,

shouldUseTransientCooldownProbeSlot,

} from "./failover-policy.js";

import {

getFallbackCandidateSkipReason,

isFallbackCandidateSkipped,

markFallbackCandidateSkipped,

} from "./fallback-skip-cache.js";

import { MissingAgentHarnessError, isMissingAgentHarnessError } from "./harness/errors.js";

import { resolveAgentHarnessPolicy } from "./harness/policy.js";

import { getRegisteredAgentHarness } from "./harness/registry.js";

import { LiveSessionModelSwitchError } from "./live-model-switch-error.js";

import {

isModelFallbackDecisionLogEnabled,

logModelFallbackDecision,

type ModelFallbackDecisionParams,

type ModelFallbackStepFields,

} from "./model-fallback-observation.js";

import type { FallbackAttempt, ModelCandidate } from "./model-fallback.types.js";

import { isCliRuntimeAlias } from "./model-runtime-aliases.js";

import { isCliProvider } from "./model-selection-cli.js";

import {

type ModelManifestNormalizationContext,

modelKey,

normalizeModelRef,

normalizeProviderId,

} from "./model-selection-normalize.js";

import {

buildConfiguredAllowlistKeys,

buildModelAliasIndex,

resolveConfiguredModelRef,

resolveModelRefFromString,

} from "./model-selection-resolve.js";

import { isAgentRunDirectAbortReason, isAgentRunRestartAbortReason } from "./run-termination.js";

import {

resolveSessionSuspensionReason,

runWithDeferredSessionSuspension,

suspendSession,

type SessionSuspensionParams,

} from "./session-suspension.js";

const log = createSubsystemLogger("model-fallback");

function isTranscriptNotContinuableError(err: unknown): boolean {

if (!err || typeof err !== "object") {

return false;

}

const code = (err as { code?: unknown }).code;

return code === TRANSCRIPT_NOT_CONTINUABLE_ERROR_CODE;

}

function hasExactConfiguredProviderModel(params: {

cfg?: OpenClawConfig;

provider: string;

model: string;

}): boolean {

const normalizedProvider = normalizeProviderId(params.provider);

const model = params.model.trim();

if (!params.cfg || !normalizedProvider || !model) {

return false;

}

for (const [providerId, providerConfig] of Object.entries(params.cfg.models?.providers ?? {})) {

if (normalizeProviderId(providerId) !== normalizedProvider) {

continue;

}

return (providerConfig.models ?? []).some((entry) => entry.id.trim() === model);

}

return false;

}

function hasConfiguredProvider(params: { cfg?: OpenClawConfig; provider: string }): boolean {

const normalizedProvider = normalizeProviderId(params.provider);

if (!params.cfg || !normalizedProvider) {

return false;

}

return Object.keys(params.cfg.models?.providers ?? {}).some(

(providerId) => normalizeProviderId(providerId) === normalizedProvider,

);

}

function allowPluginModelNormalizationForRef(params: {

cfg?: OpenClawConfig;

provider: string;

model: string;

}): boolean {

if (

params.cfg &&

!normalizePluginsConfig(params.cfg.plugins).enabled &&

hasConfiguredProvider(params)

) {

return false;

}

return !hasExactConfiguredProviderModel(params);

}

type FailoverAttribution = {

sessionId?: string;

lane?: string;

};

/**

* Structured error thrown when all model fallback candidates have been

* exhausted. Carries per-attempt details so callers can build informative

* user-facing messages (e.g. "rate-limited, retry in 30 s").

*/

export class FallbackSummaryError extends Error {

readonly attempts: FallbackAttempt[];

readonly soonestCooldownExpiry: number | null;

readonly sessionId?: string;

readonly lane?: string;

constructor(

message: string,

attempts: FallbackAttempt[],

soonestCooldownExpiry: number | null,

cause?: Error,

attribution?: FailoverAttribution,

) {

super(message, { cause });

this.name = "FallbackSummaryError";

this.attempts = attempts;

this.soonestCooldownExpiry = soonestCooldownExpiry;

this.sessionId = attribution?.sessionId;

this.lane = attribution?.lane;

}

}

export function isFallbackSummaryError(err: unknown): err is FallbackSummaryError {

return err instanceof FallbackSummaryError;

}

export type ModelFallbackRunOptions = {

allowTransientCooldownProbe?: boolean;

isFinalFallbackAttempt?: boolean;

};

type ModelFallbackRuntimeContext = {

cfg?: OpenClawConfig;

agentId?: string;

sessionKey?: string;

resolveAgentHarnessRuntimeOverride?: (provider: string, model: string) => string | undefined;

prepareAgentHarnessRuntime?: (params: {

provider: string;

model: string;

agentHarnessRuntimeOverride?: string;

}) => Promise<void> | void;

};

type ModelFallbackRunFn<T> = (

provider: string,

model: string,

options?: ModelFallbackRunOptions,

) => Promise<T>;

function isTerminalAbortReasonString(reason: string): boolean {

return isCronTerminalAbortReasonText(reason);

}

function getErrorCauseCandidates(err: Error): unknown[] {

const candidates: unknown[] = [];

if ("cause" in err && err.cause !== undefined) {

candidates.push(err.cause);

if (err.cause instanceof Error && "cause" in err.cause && err.cause.cause !== undefined) {

candidates.push(err.cause.cause);

}

}

return candidates;

}

function isTerminalAbortCandidate(candidate: unknown): boolean {

if (typeof candidate === "string") {

return isTerminalAbortReasonString(candidate);

}

if (!(candidate instanceof Error)) {

return false;

}

if (isAgentRunRestartAbortReason(candidate)) {

return true;

}

if (candidate.name === "TimeoutError") {

return true;

}

if (candidate.name === "ClientDisconnectError") {

return true;

}

return isTerminalAbortReasonString(candidate.message);

}

function isTerminalAbort(signal: AbortSignal | undefined): boolean {

if (!signal?.aborted) {

return false;

}

const reason = signal.reason;

if (reason instanceof Error) {

const candidates: unknown[] = [reason, ...getErrorCauseCandidates(reason)];

return candidates.some(isTerminalAbortCandidate);

}

return isTerminalAbortCandidate(reason);

}

function isTerminalAbortFromError(err: unknown): boolean {

if (!(err instanceof Error)) {

return false;

}

if (isAgentRunRestartAbortReason(err)) {

return true;

}

const causeCandidates = getErrorCauseCandidates(err);

if (err.name !== "AbortError") {

return false;

}

for (const candidate of causeCandidates) {

if (isAgentRunRestartAbortReason(candidate)) {

return true;

}

}

if (!isOpenClawAbortableWrapper(err)) {

return false;

}

return causeCandidates.some(isTerminalAbortCandidate);

}

function isCallerAbortSignal(signal: AbortSignal | undefined): boolean {

return signal?.aborted === true;

}

function createModelCandidateCollector(allowlist: Set<string> | null | undefined): {

candidates: ModelCandidate[];

addExplicitCandidate: (candidate: ModelCandidate) => void;

addAllowlistedCandidate: (candidate: ModelCandidate) => void;

} {

const seen = new Set<string>();

const candidates: ModelCandidate[] = [];

const addCandidate = (candidate: ModelCandidate, enforceAllowlist: boolean) => {

if (!candidate.provider || !candidate.model) {

return;

}

const key = modelKey(candidate.provider, candidate.model);

if (seen.has(key)) {

return;

}

if (enforceAllowlist && allowlist && !allowlist.has(key)) {

return;

}

seen.add(key);

candidates.push(candidate);

};

const addExplicitCandidate = (candidate: ModelCandidate) => {

addCandidate(candidate, false);

};

const addAllowlistedCandidate = (candidate: ModelCandidate) => {

addCandidate(candidate, true);

};

return { candidates, addExplicitCandidate, addAllowlistedCandidate };

}

type ModelFallbackErrorHandler = (attempt: {

provider: string;

model: string;

error: unknown;

attempt: number;

total: number;

}) => void | Promise<void>;

type ModelFallbackStepHandler = (step: ModelFallbackStepFields) => void | Promise<void>;

export type ModelFallbackResultClassification =

| {

message: string;

reason?: FailoverReason;

status?: number;

code?: string;

rawError?: string;

preserveResultOnExhaustion?: boolean;

preserveResultPriority?: number;

}

| {

error: unknown;

}

| null

| undefined;

type ModelFallbackResultClassifier<T> = (attempt: {

result: T;

provider: string;

model: string;

attempt: number;

total: number;

}) => ModelFallbackResultClassification | Promise<ModelFallbackResultClassification>;

type ModelFallbackRunResult<T> = {

outcome: "completed" | "exhausted";

result: T;

provider: string;

model: string;

attempts: FallbackAttempt[];

};

type ModelFallbackExhaustionResult<T> = Pick<

ModelFallbackRunResult<T>,

"result" | "provider" | "model"

> & {

priority: number;

};

type ModelFallbackClassifiedResult<T> = Pick<

ModelFallbackRunResult<T>,

"result" | "provider" | "model"

>;

type ModelFallbackAuthRuntime = typeof import("./model-fallback-auth.runtime.js");

const modelFallbackAuthRuntimeLoader = createLazyImportLoader<ModelFallbackAuthRuntime>(

() => import("./model-fallback-auth.runtime.js"),

);

const MAX_FALLBACK_CANDIDATE_CACHE_ENTRIES = 256;

const fallbackCandidateCache = new Map<string, ModelCandidate[]>();

async function loadModelFallbackAuthRuntime() {

return await modelFallbackAuthRuntimeLoader.load();

}

function buildFallbackSuccess<T>(params: {

result: T;

provider: string;

model: string;

attempts: FallbackAttempt[];

}): ModelFallbackRunResult<T> {

return {

outcome: "completed",

result: params.result,

provider: params.provider,

model: params.model,

attempts: params.attempts,

};

}

async function runFallbackCandidate<T>(params: {

run: ModelFallbackRunFn<T>;

provider: string;

model: string;

options?: ModelFallbackRunOptions;

deferSessionSuspension?: boolean;

onDeferredSessionSuspension?: (params: SessionSuspensionParams) => void;

attribution?: FailoverAttribution;

abortSignal?: AbortSignal;

}): Promise<{ ok: true; result: T } | { ok: false; error: unknown }> {

try {

const run = () =>

params.options

? params.run(params.provider, params.model, params.options)

: params.run(params.provider, params.model);

const result = params.deferSessionSuspension

? await runWithDeferredSessionSuspension(run, params.onDeferredSessionSuspension)

: await run();

return {

ok: true,

result,

};

} catch (err) {

if (isCommandLaneTaskTimeoutError(err)) {

throw err;

}

if (isNonProviderRuntimeCoordinationError(err)) {

throw err;

}

if (isTerminalAbort(params.abortSignal) || isCallerAbortSignal(params.abortSignal)) {

throw err;

}

if (isAgentRunDirectAbortReason(err) || isAgentRunRestartAbortReason(err)) {

throw err;

}

if (isTerminalAbortFromError(err)) {

throw err;

}

// Normalize abort-wrapped rate-limit errors (e.g. Google Vertex RESOURCE_EXHAUSTED)

// so they become FailoverErrors and continue the fallback loop instead of aborting.

const normalizedFailover = coerceToFailoverError(err, {

provider: params.provider,

model: params.model,

sessionId: params.attribution?.sessionId,

lane: params.attribution?.lane,

});

return { ok: false, error: normalizedFailover ?? err };

}

}

async function runFallbackAttempt<T>(params: {

run: ModelFallbackRunFn<T>;

provider: string;

model: string;

attempts: FallbackAttempt[];

options?: ModelFallbackRunOptions;

deferSessionSuspension?: boolean;

onDeferredSessionSuspension?: (params: SessionSuspensionParams) => void;

classifyResult?: ModelFallbackResultClassifier<T>;

attempt: number;

total: number;

attribution?: FailoverAttribution;

abortSignal?: AbortSignal;

}): Promise<

| { success: ModelFallbackRunResult<T> }

| {

error: unknown;

classifiedResult?: ModelFallbackClassifiedResult<T>;

exhaustionResult?: ModelFallbackExhaustionResult<T>;

}

> {

const runResult = await runFallbackCandidate({

run: params.run,

provider: params.provider,

model: params.model,

options: params.options,

deferSessionSuspension: params.deferSessionSuspension,

onDeferredSessionSuspension: params.onDeferredSessionSuspension,

attribution: params.attribution,

abortSignal: params.abortSignal,

});

if (runResult.ok) {

const classification = await params.classifyResult?.({

result: runResult.result,

provider: params.provider,

model: params.model,

attempt: params.attempt,

total: params.total,

});

const classifiedError = resolveResultClassificationError(classification, {

provider: params.provider,

model: params.model,

attribution: params.attribution,

});

if (classifiedError) {

if (isTerminalAbort(params.abortSignal) || isCallerAbortSignal(params.abortSignal)) {

throw toErrorObject(classifiedError, "Non-Error thrown");

}

const preserveResultOnExhaustion =

classification &&

"preserveResultOnExhaustion" in classification &&

classification.preserveResultOnExhaustion === true;

return {

error: classifiedError,

classifiedResult: {

result: runResult.result,

provider: params.provider,

model: params.model,

},

...(preserveResultOnExhaustion

? {

exhaustionResult: {

result: runResult.result,

provider: params.provider,

model: params.model,

priority:

typeof classification.preserveResultPriority === "number" &&

Number.isFinite(classification.preserveResultPriority)

? classification.preserveResultPriority

: 0,

},

}

: {}),

};

}

return {

success: buildFallbackSuccess({

result: runResult.result,

provider: params.provider,

model: params.model,

attempts: params.attempts,

}),

};

}

return { error: runResult.error };

}

function resolveResultClassificationError(

classification: ModelFallbackResultClassification,

params: { provider: string; model: string; attribution?: FailoverAttribution },

) {

if (!classification) {

return null;

}

if ("error" in classification) {

return classification.error;

}

const message = normalizeOptionalString(classification.message);

if (!message) {

return null;

}

return new FailoverError(message, {

reason: classification.reason ?? "unknown",

provider: params.provider,

model: params.model,

sessionId: params.attribution?.sessionId,

lane: params.attribution?.lane,

status: classification.status,

code: classification.code,

rawError: classification.rawError,

});

}

function sameModelCandidate(a: ModelCandidate, b: ModelCandidate): boolean {

return a.provider === b.provider && a.model === b.model;

}

function isCliAgentRuntime(runtime: string | undefined, cfg: OpenClawConfig | undefined): boolean {

const normalized = normalizeOptionalString(runtime);

if (!normalized) {

return false;

}

return isCliRuntimeAlias(normalized) || isCliProvider(normalized, cfg);

}

async function resolveModelFallbackCandidateHarnessAuthPrecheck(

params: ModelFallbackRuntimeContext & ModelCandidate,

): Promise<{ skipsProviderAuthCooldown: boolean }> {

if (!params.cfg) {

return { skipsProviderAuthCooldown: false };

}

const agentHarnessRuntimeOverride = params.resolveAgentHarnessRuntimeOverride?.(

params.provider,

params.model,

);

if (isCliProvider(params.provider, params.cfg)) {

return { skipsProviderAuthCooldown: true };

}

const agentRuntimeOverride = normalizeOptionalAgentRuntimeId(agentHarnessRuntimeOverride);

const harnessPolicy = resolveAgentHarnessPolicy({

provider: params.provider,

modelId: params.model,

config: params.cfg,

agentId: params.agentId,

sessionKey: params.sessionKey,

});

const agentRuntime =

agentRuntimeOverride && !isDefaultAgentRuntimeId(agentRuntimeOverride)

? agentRuntimeOverride

: harnessPolicy.runtime;

const agentRuntimeSource =

agentRuntimeOverride && !isDefaultAgentRuntimeId(agentRuntimeOverride)

? "model"

: harnessPolicy.runtimeSource;

if (isCliAgentRuntime(agentRuntime, params.cfg)) {

// CLI runtimes own their transport/auth, so stale OpenClaw provider

// profile state must not block the candidate before the CLI starts.

return { skipsProviderAuthCooldown: true };

}

if (agentRuntime === "openclaw") {

return { skipsProviderAuthCooldown: false };

}

if (agentRuntime === "auto" || (agentRuntime === "codex" && agentRuntimeSource === "implicit")) {

return { skipsProviderAuthCooldown: false };

}

await params.prepareAgentHarnessRuntime?.({

provider: params.provider,

model: params.model,

agentHarnessRuntimeOverride,

});

if (!getRegisteredAgentHarness(agentRuntime)) {

throw new MissingAgentHarnessError(agentRuntime);

}

// Explicit non-Codex plugin harnesses own transport/auth; stale OpenClaw

// provider cooldowns must not block the harness before it starts.

return { skipsProviderAuthCooldown: agentRuntime !== "codex" };

}

function resolveCandidateAttemptError(

described: ReturnType<typeof describeFailoverError>,

candidate: ModelCandidate,

): string {

if (

described.rawError &&

(!described.provider ||

(described.provider === candidate.provider &&

(!described.model || described.model === candidate.model)))

) {

return described.rawError;

}

return described.message;

}

function recordFailedCandidateAttempt(params: {

attempts: FallbackAttempt[];

candidate: ModelCandidate;

error: unknown;

runId?: string;

sessionId?: string;

lane?: string;

requestedProvider?: string;

requestedModel?: string;

attempt: number;

total: number;

nextCandidate?: ModelCandidate;

isPrimary: boolean;

requestedModelMatched: boolean;

fallbackConfigured: boolean;

}): ModelFallbackStepFields | undefined {

const described = describeFailoverError(params.error);

const error = resolveCandidateAttemptError(described, params.candidate);

params.attempts.push({

provider: params.candidate.provider,

model: params.candidate.model,

error,

reason: described.reason ?? "unknown",

authMode: described.authMode,

status: described.status,

code: described.code,

});

return logModelFallbackDecision({

decision: "candidate_failed",

runId: params.runId,

sessionId: params.sessionId,

lane: params.lane,

requestedProvider: params.requestedProvider ?? params.candidate.provider,

requestedModel: params.requestedModel ?? params.candidate.model,

candidate: params.candidate,

attempt: params.attempt,

total: params.total,

reason: described.reason,

status: described.status,

code: described.code,

error,

nextCandidate: params.nextCandidate,

isPrimary: params.isPrimary,

requestedModelMatched: params.requestedModelMatched,

fallbackConfigured: params.fallbackConfigured,

});

}

function appendFailedCandidateAttempt(params: {

attempts: FallbackAttempt[];

candidate: ModelCandidate;

error: unknown;

}): void {

const described = describeFailoverError(params.error);

params.attempts.push({

provider: params.candidate.provider,

model: params.candidate.model,

error: resolveCandidateAttemptError(described, params.candidate),

reason: described.reason ?? "unknown",

authMode: described.authMode,

status: described.status,

code: described.code,

});

}

function findLiveSessionModelSwitchRedirectIndex(params: {

error: LiveSessionModelSwitchError;

candidates: ModelCandidate[];

currentIndex: number;

}): number | null {

const targetKey = modelKey(params.error.provider, params.error.model);

for (let i = params.currentIndex + 1; i < params.candidates.length; i += 1) {

const candidate = params.candidates[i];

if (modelKey(candidate.provider, candidate.model) === targetKey) {

return i;

}

}

return null;

}

function throwFallbackFailureSummary(params: {

attempts: FallbackAttempt[];

candidates: ModelCandidate[];

lastError: unknown;

label: string;

formatAttempt: (attempt: FallbackAttempt) => string;

soonestCooldownExpiry?: number | null;

attribution?: FailoverAttribution;

cfg?: OpenClawConfig;

agentDir?: string;

}): never {

if (params.attempts.length <= 1 && params.lastError) {

throw toErrorObject(params.lastError, "Non-Error thrown");

}

if (params.attribution?.sessionId) {

void suspendSession({

cfg: params.cfg,

agentDir: params.agentDir,

sessionId: params.attribution.sessionId,

laneId: params.attribution.lane,

reason: "circuit_open",

failedProvider: params.attempts[params.attempts.length - 1]?.provider ?? "unknown",

failedModel: params.attempts[params.attempts.length - 1]?.model ?? "unknown",

});

}

const summary =

params.attempts.length > 0 ? params.attempts.map(params.formatAttempt).join(" | ") : "unknown";

const remediation = buildFailoverRemediationHint(params.lastError);

const message = remediation

? `All ${params.label} failed (${params.attempts.length || params.candidates.length}): ${summary}. ${remediation}`

: `All ${params.label} failed (${params.attempts.length || params.candidates.length}): ${summary}`;

throw new FallbackSummaryError(

message,

params.attempts,

params.soonestCooldownExpiry ?? null,

params.lastError instanceof Error ? params.lastError : undefined,

params.attribution,

);

}

function resolveFallbackSoonestCooldownExpiry(params: {

authRuntime: ModelFallbackAuthRuntime | null;

authStore: AuthProfileStore | null;

agentDir?: string;

cfg: OpenClawConfig | undefined;

candidates: ModelCandidate[];

}): number | null {

if (!params.authRuntime || !params.authStore) {

return null;

}

// Refresh from persisted state because embedded attempts can update auth

// cooldowns through a separate store instance while the fallback loop runs.

const refreshedStore = params.authRuntime.loadAuthProfileStoreForRuntime(params.agentDir, {

readOnly: true,

externalCli: externalCliDiscoveryForProviders({

cfg: params.cfg,

providers: params.candidates.map((candidate) => candidate.provider),

}),

});

let soonest: number | null = null;

for (const candidate of params.candidates) {

const ids = params.authRuntime.resolveAuthProfileOrder({

cfg: params.cfg,

store: refreshedStore,

provider: candidate.provider,

});

const candidateSoonest = params.authRuntime.getSoonestCooldownExpiry(refreshedStore, ids, {

forModel: candidate.model,

});

if (

typeof candidateSoonest === "number" &&

Number.isFinite(candidateSoonest) &&

(soonest === null || candidateSoonest < soonest)

) {

soonest = candidateSoonest;

}

}

return soonest;

}

export function resolveImageFallbackCandidates(

params: {

cfg: OpenClawConfig | undefined;

defaultProvider: string;

modelOverride?: string;

} & ModelManifestNormalizationContext,

): ModelCandidate[] {

const aliasIndex = buildModelAliasIndex({

cfg: params.cfg ?? {},

defaultProvider: params.defaultProvider,

manifestPlugins: params.manifestPlugins,

});

const allowlist = buildConfiguredAllowlistKeys({

cfg: params.cfg,

defaultProvider: params.defaultProvider,

manifestPlugins: params.manifestPlugins,

});

const { candidates, addExplicitCandidate, addAllowlistedCandidate } =

createModelCandidateCollector(allowlist);

const addRaw = (raw: string, opts?: { allowlist?: boolean }) => {

const resolved = resolveModelRefFromString({

cfg: params.cfg,

raw,

defaultProvider: params.defaultProvider,

aliasIndex,

manifestPlugins: params.manifestPlugins,

});

if (!resolved) {

return;

}

if (opts?.allowlist) {

addAllowlistedCandidate(resolved.ref);

return;

}

addExplicitCandidate(resolved.ref);

};

if (params.modelOverride?.trim()) {

addRaw(params.modelOverride);

} else {

const primary = resolveAgentModelPrimaryValue(params.cfg?.agents?.defaults?.imageModel);

if (primary?.trim()) {

addRaw(primary);

}

}

const imageFallbacks = resolveAgentModelFallbackValues(params.cfg?.agents?.defaults?.imageModel);

for (const raw of imageFallbacks) {

// Explicitly configured image fallbacks should remain reachable even when a

// model allowlist is present.

addRaw(raw);

}

return candidates;

}

export function resolveImageFallbackDefaultProvider(cfg: OpenClawConfig | undefined): string {

const configuredPrimary = resolveAgentModelPrimaryValue(cfg?.agents?.defaults?.imageModel);

if (configuredPrimary?.trim()) {

const aliasIndex = buildModelAliasIndex({

cfg: cfg ?? {},

defaultProvider: DEFAULT_PROVIDER,

});

const resolved = resolveModelRefFromString({

cfg,

raw: configuredPrimary,

defaultProvider: DEFAULT_PROVIDER,

aliasIndex,

});

if (resolved?.ref.provider) {

return resolved.ref.provider;

}

}

return DEFAULT_PROVIDER;

}

export const testing = {

resolveFallbackCandidates: resolveModelCandidateChain,

resolveImageFallbackCandidates,

resolveCooldownDecision,

resolveSessionSuspensionReason,

shouldDiscardDeferredSessionSuspension,

} as const;

export function resolveModelCandidateChain(

params: {

cfg: OpenClawConfig | undefined;

provider: string;

model: string;

/** Optional explicit fallbacks list; when provided (even empty), replaces agents.defaults.model.fallbacks. */

fallbacksOverride?: string[];

} & ModelManifestNormalizationContext,

): ModelCandidate[] {

const cacheKey = resolveFallbackCandidateCacheKey(params);

if (cacheKey) {

const cached = fallbackCandidateCache.get(cacheKey);

if (cached) {

return cached.map(cloneModelCandidate);

}

}

const candidates = resolveFallbackCandidatesUncached(params);

if (cacheKey) {

fallbackCandidateCache.set(cacheKey, candidates.map(cloneModelCandidate));

while (fallbackCandidateCache.size > MAX_FALLBACK_CANDIDATE_CACHE_ENTRIES) {

const oldest = fallbackCandidateCache.keys().next();

if (oldest.done) {

break;

}

fallbackCandidateCache.delete(oldest.value);

}

}

return candidates;

}

function cloneModelCandidate(candidate: ModelCandidate): ModelCandidate {

return {

provider: candidate.provider,

model: candidate.model,

};

}

function resolveFallbackCandidateCacheKey(

params: {

cfg: OpenClawConfig | undefined;

provider: string;

model: string;

fallbacksOverride?: string[];

} & ModelManifestNormalizationContext,

): string | null {

if (params.manifestPlugins) {

return null;

}

const workspaceDir = getActivePluginRegistryWorkspaceDirFromState();

const env = process.env;

const pluginMetadata = getCurrentPluginMetadataSnapshot({

env,

workspaceDir,

allowWorkspaceScopedSnapshot: true,

});

const providerLoadMetadata = getCurrentPluginMetadataSnapshot({

config: params.cfg,

env,

workspaceDir,

allowWorkspaceScopedSnapshot: true,

});

if (

isPluginProvidersLoadInFlight({

config: params.cfg,

workspaceDir,

env,

...(providerLoadMetadata ? { pluginMetadataSnapshot: providerLoadMetadata } : {}),

activate: false,

bundledProviderVitestCompat: true,

})

) {

return null;

}

const registryState = getPluginRegistryState();

return JSON.stringify({

provider: params.provider,

model: params.model,

fallbacksOverride: params.fallbacksOverride,

agentsDefaultsModel: params.cfg?.agents?.defaults?.model,

agentsDefaultsModels: params.cfg?.agents?.defaults?.models,

modelProviders: resolveFallbackCandidateModelProviderCacheParts(params.cfg),

pluginControlPlane: resolvePluginControlPlaneFingerprint({

config: params.cfg,

env,

workspaceDir,

}),

pluginMetadataFingerprint: pluginMetadata?.configFingerprint ?? null,

pluginRegistryKey: registryState?.key ?? null,

pluginRegistryVersion: registryState?.activeVersion ?? null,

pluginWorkspaceDir: workspaceDir ?? null,

});

}

function resolveFallbackCandidateModelProviderCacheParts(cfg: OpenClawConfig | undefined): unknown {

const providers = cfg?.models?.providers;

if (!providers) {

return undefined;

}

return Object.entries(providers).map(([providerId, providerConfig]) => ({

providerId,

api: typeof providerConfig?.api === "string" ? providerConfig.api : undefined,

models: Array.isArray(providerConfig?.models)

? providerConfig.models

.map((entry) => (typeof entry?.id === "string" ? entry.id : undefined))

.filter((id): id is string => id !== undefined)

: [],

}));

}

function resolveFallbackCandidatesUncached(

params: {

cfg: OpenClawConfig | undefined;

provider: string;

model: string;

/** Optional explicit fallbacks list; when provided (even empty), replaces agents.defaults.model.fallbacks. */

fallbacksOverride?: string[];

} & ModelManifestNormalizationContext,

): ModelCandidate[] {

const primary = params.cfg