const log = createSubsystemLogger("errors");

const sandboxToolPolicyAuditMessages = new WeakSet<AssistantMessage>();

export const GENERIC_ASSISTANT_ERROR_TEXT = "LLM request failed.";

export const AUTH_INVALID_TOKEN_USER_TEXT =

"Authentication failed (provider returned HTTP 401). " +

"Your provider token may have expired — try the request again in a moment. " +

"If the failure persists, re-authenticate this provider.";

const PROVIDER_SCHEMA_REJECTION_USER_TEXT =

"LLM request failed: provider rejected the request schema or tool payload.";

const MODEL_NOT_FOUND_USER_TEXT =

}

if (providerRuntimeFailureKind === "auth_invalid_token") {

return (

"Authentication failed (provider returned HTTP 401). " +

"Your provider token may have expired — try the request again in a moment. " +

"If the failure persists, re-authenticate this provider."

);

return AUTH_INVALID_TOKEN_USER_TEXT;

}

if (providerRuntimeFailureKind === "upstream_html") {

} from "./agent-runner-execution.js";

import { HEARTBEAT_EXTERNAL_RUN_FAILURE_TEXT } from "./agent-runner-failure-copy.js";

import {

PROVIDER_AUTHENTICATION_ERROR_USER_MESSAGE,

PROVIDER_CONVERSATION_STATE_ERROR_USER_MESSAGE,

PROVIDER_INTERNAL_ERROR_USER_MESSAGE,

PROVIDER_RATE_LIMIT_OR_QUOTA_ERROR_USER_MESSAGE,

},

);

it.each(NON_DIRECT_FAILURE_SURFACE_CASES)(

"surfaces provider authentication failures in $label chats",

async (testCase) => {

const rawError =

"unexpected status 401 Unauthorized: Missing bearer or basic authentication in header, url: https://api.openai.com/v1/responses";

state.runEmbeddedAgentMock.mockRejectedValueOnce(

new FailoverError("LLM request unauthorized.", {

reason: "auth",

provider: "openai",

model: "gpt-5.5",

status: 401,

rawError,

}),

);

const runAgentTurnWithFallback = await getRunAgentTurnWithFallback();

const result = await runAgentTurnWithFallback(

createMinimalRunAgentTurnParams({

sessionCtx: createNonDirectFailureSessionCtx(testCase),

}),

);

expect(result.kind).toBe("final");

if (result.kind === "final") {

expect(result.payload.isError).toBe(true);

expect(result.payload.text).toBe(PROVIDER_AUTHENTICATION_ERROR_USER_MESSAGE);

expect(result.payload.text).not.toBe(SILENT_REPLY_TOKEN);

expect(result.payload.text).not.toContain(rawError);

}

},

);

it.each(NON_DIRECT_FAILURE_SURFACE_CASES)(

"surfaces rate-limit fallback copy in $label chats",

async (testCase) => {

/** Tests provider request error classification for retry/fallback decisions. */

import { describe, expect, it } from "vitest";

import { FailoverError } from "../../agents/failover-error.js";

import {

classifyProviderRequestError,

PROVIDER_AUTHENTICATION_ERROR_USER_MESSAGE,

PROVIDER_CONVERSATION_STATE_ERROR_USER_MESSAGE,

PROVIDER_INTERNAL_ERROR_USER_MESSAGE,

PROVIDER_RATE_LIMIT_OR_QUOTA_ERROR_USER_MESSAGE,

} from "./provider-request-error-classifier.js";

describe("provider request error classifier", () => {

it("classifies provider HTTP 401 authentication failures", () => {

const message =

"unexpected status 401 Unauthorized: Missing bearer or basic authentication in header, url: https://api.openai.com/v1/responses";

expect(classifyProviderRequestError(new Error(message))).toEqual({

code: "provider_authentication_error",

userMessage: PROVIDER_AUTHENTICATION_ERROR_USER_MESSAGE,

technicalMessage: message,

});

});

it("classifies typed authentication failures without relying on raw provider text", () => {

const error = new FailoverError("LLM request unauthorized.", {

reason: "auth",

provider: "openai",

model: "gpt-5.5",

status: 401,

});

expect(classifyProviderRequestError(error)).toEqual({

code: "provider_authentication_error",

userMessage: PROVIDER_AUTHENTICATION_ERROR_USER_MESSAGE,

technicalMessage: "LLM request unauthorized.",

});

});

it("does not label typed HTTP 403 authorization failures as HTTP 401", () => {

const error = new FailoverError("Provider access denied.", {

reason: "auth_permanent",

provider: "openai",

model: "gpt-5.5",

status: 403,

});

expect(classifyProviderRequestError(error)).toBeUndefined();

});

it("leaves unrelated HTTP 401 failures unclassified", () => {

expect(

classifyProviderRequestError(

new Error("401 input item id does not belong to this conversation"),

),

).toBeUndefined();

});

it.each([

[

"OpenAI missing custom tool output",

// Classifies provider request failures into retry and user-facing categories.

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

import {

AUTH_INVALID_TOKEN_USER_TEXT,

classifyProviderRuntimeFailureKind,

} from "../../agents/embedded-agent-helpers/errors.js";

import { isFailoverError } from "../../agents/failover-error.js";

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

/** Provider request error classes that get a specialized user-facing reply. */

export type ProviderRequestErrorCode =

| "provider_authentication_error"

| "provider_conversation_state_error"

| "provider_internal_error"

| "provider_rate_limit_or_quota_error";

export const PROVIDER_INTERNAL_ERROR_USER_MESSAGE =

"⚠️ The model provider returned a temporary internal error before replying. Try again in a moment, or switch to another model if it keeps happening.";

export const PROVIDER_AUTHENTICATION_ERROR_USER_MESSAGE = `⚠️ ${AUTH_INVALID_TOKEN_USER_TEXT}`;

/** Classifies provider request failures that are actionable for users. */

export function classifyProviderRequestError(

err: unknown,

): ProviderRequestErrorClassification | undefined {

const technicalMessage = formatErrorMessage(err);

const isTypedAuthFailure = isFailoverError(err) && err.reason === "auth" && err.status === 401;

if (

isTypedAuthFailure ||

classifyProviderRuntimeFailureKind(technicalMessage) === "auth_invalid_token"

) {

return {

code: "provider_authentication_error",

userMessage: PROVIDER_AUTHENTICATION_ERROR_USER_MESSAGE,

technicalMessage,

};

}

if (

hasHttp429Evidence(err, technicalMessage) &&

isGenericProviderRuntimeErrorMessage(technicalMessage)