LibreChat/packages/api/src/agents/errors.ts
Danny Avila 345cf8877f
🍵 fix: Support Renewable MCP Credentials for Schedules (#15908)
* fix(schedules): forward renewable MCP credentials

* fix(schedules): require unattended MCP credentials

* fix(schedules): resolve MCP credentials during execution

* refactor(schedules): inject unattended credentials

* fix(schedules): scope renewable credential resolution

* fix: isolate lazy scheduled OBO credentials across MCP lifecycle

* fix: preserve MCP cancellation and retryable credential lookup

* fix: bind MCP cancellation to the owning run signal

* test: supply flow manager in OBO cancellation regression

* fix: preserve MCP cancellation across exchange and API ingress

* style: sort MCP manager imports

* fix: propagate cancellation through agent discovery

* test: preserve agent discovery edge literals

* fix: propagate agent initialization cancellation

* fix: expose initialization signal in OpenAI adapter
2026-09-14 10:27:47 -04:00

163 lines
5.8 KiB
TypeScript

import {
ErrorTypes,
parseLangChainErrorCode,
stripLangChainTroubleshootingUrl,
} from 'librechat-data-provider';
import { isOwnedAbortError } from '~/utils/errors';
export const AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE = 'AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE';
export const AGENT_ATTACHMENT_LIMIT_EXCEEDED = 'AGENT_ATTACHMENT_LIMIT_EXCEEDED';
const FATAL_AGENT_INITIALIZATION_CODES = new Set(
[
AGENT_ATTACHMENT_LIMIT_EXCEEDED,
ErrorTypes.RESOURCE_RECOVERY_REQUIRED,
ErrorTypes.STATEFUL_CODE_ENVIRONMENT_NOT_ALLOWED,
ErrorTypes.CODE_WORKSPACE_UNAVAILABLE,
].filter((code): code is string => typeof code === 'string'),
);
export function createStatefulCodeEnvironmentPolicyError(environment: string): Error {
return Object.assign(
new Error(`Stateful code environment is not allowed by this deployment: ${environment}`),
{
code: ErrorTypes.STATEFUL_CODE_ENVIRONMENT_NOT_ALLOWED,
status: 403,
statusCode: 403,
},
);
}
export interface FatalAgentInitializationOptions {
signal?: AbortSignal;
/**
* Skill `allowed-tools` may add an MCP tool beyond the agent's configured
* baseline. That union load is allowed to retry without the skill extras;
* a second failure from the baseline still propagates normally.
*/
allowExpectedMCPFallback?: boolean;
}
function getErrorCode(error: unknown): unknown {
if (error == null || typeof error !== 'object') {
return undefined;
}
return (error as { code?: unknown }).code;
}
/**
* Returns whether agent initialization must abort instead of using the
* legacy soft-failure behavior for unavailable optional tools or agents.
* Keep fatal initialization policy centralized here so every topology and
* ingress path makes the same decision when new invariant errors are added.
*/
export function isFatalAgentInitializationError(
error: unknown,
options: FatalAgentInitializationOptions = {},
): boolean {
const code = getErrorCode(error);
return (
isOwnedAbortError(error, options.signal) ||
FATAL_AGENT_INITIALIZATION_CODES.has(code as string) ||
(code === AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE && options.allowExpectedMCPFallback !== true)
);
}
/** Fallback shown when provider error text must not reach the user. */
export const GENERIC_PROVIDER_ERROR = 'An error occurred while processing the request';
/**
* LangChain error codes we answer with localized copy. Codes absent here keep the provider's own
* message (minus the docs URL), which is more specific than any generic string we could write.
*/
const LANGCHAIN_ERROR_TYPES: Record<string, ErrorTypes> = {
MODEL_NOT_FOUND: ErrorTypes.MODEL_NOT_FOUND,
MODEL_RATE_LIMIT: ErrorTypes.MODEL_RATE_LIMIT,
};
/**
* Reads LangChain's classification off the error, falling back to the docs URL it stamps into the
* message so a re-thrown or serialized error still classifies.
*/
export function getLangChainErrorCode(error: unknown): string | undefined {
if (error == null || typeof error !== 'object') {
return parseLangChainErrorCode(error);
}
const { lc_error_code: code, message } = error as { lc_error_code?: unknown; message?: unknown };
if (typeof code === 'string' && code.length > 0) {
return code.toUpperCase();
}
return parseLangChainErrorCode(message);
}
/**
* Typed payload the client localizes for a classified LangChain failure, or `undefined` when the
* code has no localized copy and the provider's own message should be shown instead.
*/
export function resolveLangChainError(error: unknown): string | undefined {
const code = getLangChainErrorCode(error);
const type = code == null ? undefined : LANGCHAIN_ERROR_TYPES[code];
return type == null ? undefined : JSON.stringify({ type });
}
/**
* Provider failure text for OpenAI-compatible responses, which carry raw strings rather than the
* typed payloads the LibreChat client localizes.
*/
export function getUserFacingProviderError(error: unknown, protectionEnabled: boolean): string {
if (protectionEnabled) {
return GENERIC_PROVIDER_ERROR;
}
if (!(error instanceof Error)) {
return 'An error occurred';
}
return stripLangChainTroubleshootingUrl(error.message) || GENERIC_PROVIDER_ERROR;
}
/**
* LangGraph's stable machine identifier for "the graph ran out of supersteps".
* Set as `lc_error_code` on the `GraphRecursionError` thrown by the Pregel loop
* when `loop.status === 'out_of_steps'`.
*/
const GRAPH_RECURSION_LIMIT_CODE = 'GRAPH_RECURSION_LIMIT';
/** Bounded `cause` walk: a graph error may be rethrown wrapped by an outer node. */
const MAX_CAUSE_DEPTH = 4;
function readErrorProperty(error: object, property: PropertyKey): unknown {
try {
return Reflect.get(error, property);
} catch {
return undefined;
}
}
/**
* Whether `error` is the agent graph exhausting its per-turn step budget
* (`recursionLimit`), as opposed to anything actually going wrong.
*
* This is a normal terminal condition, not a failure: the turn is persisted as
* `unfinished` with `Constants.TOOL_CALL_LIMIT_FINISH_REASON` so the UI can offer
* to continue, instead of surfacing a red error bubble the user cannot act on.
*
* Both markers are checked because they fail independently. `lc_error_code` is the
* documented contract but is only present on errors constructed with the fields
* argument, while `name` is assigned in the constructor body and therefore survives
* class-name minification. Either one alone is sufficient evidence.
*/
export function isStepLimitError(error: unknown): boolean {
let current = error;
for (let depth = 0; depth < MAX_CAUSE_DEPTH && current != null; depth++) {
if (typeof current !== 'object') {
return false;
}
if (
readErrorProperty(current, 'lc_error_code') === GRAPH_RECURSION_LIMIT_CODE ||
readErrorProperty(current, 'name') === 'GraphRecursionError'
) {
return true;
}
current = readErrorProperty(current, 'cause');
}
return false;
}