Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

20.3 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0

import ast
import re
from typing import Any, Iterator

import httpx

from openviking.pyagfs.exceptions import (
    AGFSAlreadyExistsError,
    AGFSClientError,
    AGFSConfigError,
    AGFSConnectionError,
    AGFSDirectoryNotEmptyError,
    AGFSHTTPError,
    AGFSInternalError,
    AGFSInvalidOperationError,
    AGFSInvalidPathError,
    AGFSIoError,
    AGFSIsADirectoryError,
    AGFSMountPointNotFoundError,
    AGFSNetworkError,
    AGFSNotADirectoryError,
    AGFSNotFoundError,
    AGFSNotSupportedError,
    AGFSPermissionDeniedError,
    AGFSPluginError,
    AGFSResourceExhaustedError,
    AGFSSerializationError,
    AGFSTimeoutError,
    GitConcurrentCommitError,
)
from openviking.storage.errors import LockAcquisitionError, ResourceBusyError
from openviking.utils.exceptions import (
    HTTP_STATUS_TO_ERROR_CODE,
    AllCredentialsFailedError,
    error_code_from_http_status,
)
from openviking_cli.exceptions import (
    ConflictError,
    FailedPreconditionError,
    InternalError,
    InvalidArgumentError,
    InvalidURIError,
    NotFoundError,
    OpenVikingError,
    PermissionDeniedError,
    ResourceExhaustedError,
    UnavailableError,
    UnimplementedError,
)

_KNOWN_HTTP_STATUS_CODES = frozenset(HTTP_STATUS_TO_ERROR_CODE)
_UPSTREAM_ERROR_MARKERS = (
    "api error",
    "apierror",
    "badrequesterror",
    "authenticationerror",
    "permissiondeniederror",
    "ratelimiterror",
    "httpstatuserror",
    "openai",
    "litellm",
    "volcengine",
    "ark",
    "gemini",
    "jina",
    "voyage",
    "cohere",
    "dashscope",
    "minimax",
    "embedding",
    "embedder",
    "vlm",
    "model",
    "upstream",
    "invalid api key",
    "unauthorized",
    "forbidden",
    "too many requests",
    "rate limit",
    "quota",
    "accountoverdue",
)
_API_KEY_CONFIG_MARKERS = (
    "vlm configuration",
    "embedding",
    "embedder",
    "provider",
    "openai",
    "azure",
    "volcengine",
    "jina",
    "gemini",
    "voyage",
    "dashscope",
    "minimax",
    "cohere",
)
_HTTP_STATUS_PATTERNS = (
    re.compile(r"\bHTTP\s*(\d{3})\b", re.IGNORECASE),
    re.compile(r"\bstatus(?:\s+code)?\s*[:=]?\s*(\d{3})\b", re.IGNORECASE),
    re.compile(r"\berror\s+code\s*[:=]?\s*(\d{3})\b", re.IGNORECASE),
)


def _iter_exception_chain(exc: Exception) -> Iterator[BaseException]:
    seen: set[int] = set()
    pending: list[BaseException] = [exc]
    while pending:
        current = pending.pop(0)
        ident = id(current)
        if ident in seen:
            continue
        seen.add(ident)
        yield current
        for nested in (getattr(current, "__cause__", None), getattr(current, "__context__", None)):
            if isinstance(nested, BaseException) and id(nested) not in seen:
                pending.append(nested)


def _coerce_http_status(value: Any) -> int | None:
    if isinstance(value, bool) or value is None:
        return None
    try:
        status = int(value)
    except (TypeError, ValueError):
        return None
    if 100 <= status <= 599:
        return status
    return None


def _normalize_message(message: str) -> str:
    return " ".join(str(message).split())


def _dedupe_messages(messages: list[str]) -> list[str]:
    result: list[str] = []
    for message in messages:
        normalized = _normalize_message(message)
        if not normalized:
            continue
        if any(normalized == existing or normalized in existing for existing in result):
            continue
        result = [existing for existing in result if existing not in normalized]
        result.append(normalized)
    return result


def _exception_chain_text(exc: Exception) -> str:
    return "\n".join(_dedupe_messages([str(item) for item in _iter_exception_chain(exc)]))


def _trim_message(message: str, limit: int = 500) -> str:
    normalized = _normalize_message(message)
    if len(normalized) <= limit:
        return normalized
    return normalized[: limit - 3] + "..."


def _iter_braced_segments(text: str) -> Iterator[str]:
    start: int | None = None
    depth = 0
    quote: str | None = None
    escaped = False
    for index, char in enumerate(text):
        if quote is not None:
            if escaped:
                escaped = False
            elif char == "\\":
                escaped = True
            elif char == quote:
                quote = None
            continue
        if char in {'"', "'"}:
            quote = char
        elif char == "{":
            if depth == 0:
                start = index
            depth += 1
        elif char == "}" and depth:
            depth -= 1
            if depth == 0 and start is not None:
                yield text[start : index + 1]
                start = None


def _extract_payload_message(payload: Any) -> str | None:
    if not isinstance(payload, dict):
        return None
    error = payload.get("error")
    if isinstance(error, dict):
        message = error.get("message")
        if isinstance(message, str) and message.strip():
            return message.strip()
    message = payload.get("message")
    if isinstance(message, str) and message.strip():
        return message.strip()
    return None


def _extract_provider_error_message(text: str) -> str | None:
    for segment in _iter_braced_segments(text):
        try:
            payload = ast.literal_eval(segment)
        except (SyntaxError, ValueError):
            continue
        message = _extract_payload_message(payload)
        if message:
            return message
    return None


def _upstream_detail_message(exc: Exception) -> str:
    text = _exception_chain_text(exc)
    return _extract_provider_error_message(text) or text


def _looks_like_upstream_model_error(exc: Exception) -> bool:
    text = _exception_chain_text(exc).lower()
    return any(marker in text for marker in _UPSTREAM_ERROR_MARKERS)


def _is_model_api_key_configuration_error(exc: Exception) -> bool:
    text = _exception_chain_text(exc).lower()
    if "api_key" not in text and "api key" not in text:
        return False
    if "invalid api key" in text or "unauthorized" in text:
        return False
    missing_key_phrases = (
        "requires 'api_key'",
        "requires api_key",
        "api_key is required",
        "api key is required",
        "requires 'api key'",
    )
    if not any(phrase in text for phrase in missing_key_phrases):
        return False
    if any(marker in text for marker in _API_KEY_CONFIG_MARKERS):
        return True
    return text.strip() in (
        "api_key is required",
        "api key is required",
    )


def _extract_structured_http_status(
    exc: Exception,
) -> tuple[int, BaseException] | tuple[None, None]:
    for item in _iter_exception_chain(exc):
        for attr in ("status_code", "http_status", "status"):
            status = _coerce_http_status(getattr(item, attr, None))
            if status is not None:
                return status, item
        code = getattr(item, "code", None)
        if not isinstance(code, str):
            status = _coerce_http_status(code)
            if status is not None:
                return status, item
        response = getattr(item, "response", None)
        if response is not None:
            for attr in ("status_code", "status"):
                status = _coerce_http_status(getattr(response, attr, None))
                if status is not None:
                    return status, item
    return None, None


def _extract_text_http_status(exc: Exception) -> int | None:
    if not _looks_like_upstream_model_error(exc):
        return None
    text = _exception_chain_text(exc)
    for pattern in _HTTP_STATUS_PATTERNS:
        match = pattern.search(text)
        if match:
            status = _coerce_http_status(match.group(1))
            if status is not None:
                return status
    for status in _KNOWN_HTTP_STATUS_CODES:
        if re.search(rf"\b{status}\b", text):
            return status
    return None


def _extract_vlm_info(exc: Exception | None) -> tuple[str | None, str | None]:
    """Extract model name and api_base from the exception chain, if annotated."""
    if exc is None:
        return None, None
    for item in _iter_exception_chain(exc):
        model = getattr(item, "_vlm_model", None)
        api_base = getattr(item, "_vlm_api_base", None)
        if model or api_base:
            return model, api_base
    return None, None


def _build_upstream_error(
    *,
    code: str,
    message: str,
    status: int | None = None,
    source: BaseException | None = None,
    vlm_context: BaseException | None = None,
) -> OpenVikingError:
    labels = {
        "INVALID_ARGUMENT": "Upstream model request was rejected",
        "UNAUTHENTICATED": "Upstream model authentication failed",
        "PERMISSION_DENIED": "Upstream model permission denied",
        "NOT_FOUND": "Upstream model resource not found",
        "CONFLICT": "Upstream model request conflicted",
        "RESOURCE_EXHAUSTED": "Upstream model quota or rate limit exceeded",
        "DEADLINE_EXCEEDED": "Upstream model request timed out",
        "UNAVAILABLE": "Upstream model service unavailable",
    }
    detail_message = _trim_message(message)
    display = labels.get(code, "Upstream model error")
    if status is not None:
        display = f"{display} (HTTP {status})"
    if detail_message:
        display = f"{display}: {detail_message}"
    details: dict[str, Any] = {"upstream_message": detail_message}
    if status is not None:
        details["upstream_status_code"] = status
    if source is not None:
        details["upstream_error_type"] = type(source).__name__
    # Search for VLM model/api_base annotations. vlm_context is the outermost
    # exception (where failover wrappers attach the annotation); source may be
    # an inner exception from the chain.
    vlm_model, vlm_api_base = _extract_vlm_info(vlm_context)
    if not vlm_model and not vlm_api_base:
        vlm_model, vlm_api_base = _extract_vlm_info(source)
    if vlm_model:
        details["vlm_model"] = vlm_model
        display = f"{display}\n  Model: {vlm_model}"
    if vlm_api_base:
        details["vlm_api_base"] = vlm_api_base
        display = f"{display}\n  API base: {vlm_api_base}"
    return OpenVikingError(display, code=code, details=details)


def _map_upstream_api_error(exc: Exception) -> OpenVikingError | None:
    for item in _iter_exception_chain(exc):
        if isinstance(item, AllCredentialsFailedError):
            failures = [_map_upstream_api_error(error) for _, _, error, _ in item.errors]
            codes = {failure.code if failure is not None else "INTERNAL" for failure in failures}
            # A mixed failure has no single accurate status. Do not infer one
            # from whichever credential happens to appear first in the message.
            if len(codes) != 1 or "INTERNAL" in codes:
                return InternalError(str(exc))
            return _build_upstream_error(
                code=codes.pop(),
                message=_upstream_detail_message(exc),
                source=item,
                vlm_context=exc,
            )

    if _is_model_api_key_configuration_error(exc):
        return FailedPreconditionError(
            "Model provider API key is not configured",
            details={"reason": _trim_message(_exception_chain_text(exc))},
        )

    status, source = _extract_structured_http_status(exc)
    if status is None:
        for item in _iter_exception_chain(exc):
            if isinstance(item, httpx.TimeoutException):
                code = "DEADLINE_EXCEEDED"
            elif isinstance(item, (httpx.NetworkError, httpx.RemoteProtocolError)):
                code = "UNAVAILABLE"
            else:
                continue
            return _build_upstream_error(
                code=code,
                message=_upstream_detail_message(exc),
                source=item,
                vlm_context=exc,
            )
        status = _extract_text_http_status(exc)
    if status is not None:
        code = error_code_from_http_status(status, default="UNKNOWN")
        if code == "UNKNOWN":
            return None
        return _build_upstream_error(
            code=code,
            status=status,
            source=source,
            message=_upstream_detail_message(exc),
            vlm_context=exc,
        )

    if not _looks_like_upstream_model_error(exc):
        return None
    text = _exception_chain_text(exc)
    lowered = text.lower()
    if "invalid api key" in lowered or "unauthorized" in lowered:
        return _build_upstream_error(
            code="UNAUTHENTICATED",
            message=_upstream_detail_message(exc),
            source=exc,
            vlm_context=exc,
        )
    if "forbidden" in lowered:
        return _build_upstream_error(
            code="PERMISSION_DENIED",
            message=_upstream_detail_message(exc),
            source=exc,
            vlm_context=exc,
        )
    if any(
        marker in lowered
        for marker in (
            "too many requests",
            "rate limit",
            "ratelimit",
            "quota",
            "accountoverdue",
            "resource exhausted",
        )
    ):
        return _build_upstream_error(
            code="RESOURCE_EXHAUSTED",
            message=_upstream_detail_message(exc),
            source=exc,
            vlm_context=exc,
        )
    return None


def is_not_found_error(exc: Exception) -> bool:
    if isinstance(exc, FileNotFoundError):
        return True
    if isinstance(exc, AGFSNotFoundError):
        return True
    if isinstance(exc, AGFSHTTPError) and exc.status_code == 404:
        return True
    message = str(exc).lower()
    return any(
        marker in message
        for marker in (
            "not found",
            "no such file",
            "does not exist",
        )
    )


def is_invalid_uri_error(exc: Exception) -> bool:
    message = str(exc).lower()
    return any(
        marker in message
        for marker in (
            "invalid uri",
            "invalid viking uri",
            "invalid viking://",
        )
    )


def _not_found_error(resource: str | None, resource_type: str) -> NotFoundError:
    return NotFoundError(resource or "", resource_type)


def _resource_details(resource: str | None) -> dict[str, str] | None:
    return {"resource": resource} if resource else None


def _file_directory_details(resource: str | None) -> dict[str, str]:
    details = {"expected": "file", "actual": "directory"}
    if resource:
        details["resource"] = resource
    return details


def map_exception(
    exc: Exception,
    *,
    resource: str | None = None,
    resource_type: str = "resource",
) -> OpenVikingError | None:
    if isinstance(exc, OpenVikingError):
        return exc
    if isinstance(exc, ResourceBusyError):
        details: dict[str, Any] = {
            "resource": exc.uri or resource,
            "uri": exc.uri or resource,
            "conflict_type": exc.conflict_type,
            "retryable": exc.retryable,
        }
        return OpenVikingError(str(exc), code="CONFLICT", details=details)
    if isinstance(exc, LockAcquisitionError):
        details = {
            "resource": resource,
            "uri": resource,
            "conflict_type": "path_busy",
            "retryable": True,
        }
        return OpenVikingError(str(exc), code="CONFLICT", details=details)
    if isinstance(exc, GitConcurrentCommitError):
        details = {
            "conflict_type": "git_ref_cas",
            "retryable": True,
        }
        return OpenVikingError(
            str(exc) or "concurrent git commit", code="CONFLICT", details=details
        )
    if isinstance(exc, PermissionError):
        return PermissionDeniedError(str(exc), resource=resource)
    if isinstance(exc, FileNotFoundError):
        return _not_found_error(resource, resource_type)
    if isinstance(exc, ValueError):
        if _is_model_api_key_configuration_error(exc):
            return _map_upstream_api_error(exc)
        message = str(exc)
        if is_invalid_uri_error(exc):
            return InvalidURIError(resource or message, message)
        return InvalidArgumentError(message, details={"resource": resource} if resource else None)
    if isinstance(exc, (AGFSConnectionError, AGFSTimeoutError)):
        return UnavailableError("storage backend", reason=str(exc))
    if isinstance(exc, AGFSHTTPError):
        if exc.status_code == 404 or is_not_found_error(exc):
            return _not_found_error(resource, resource_type)
        if exc.status_code == 403:
            return PermissionDeniedError(str(exc), resource=resource)
        if exc.status_code == 409:
            return ConflictError(str(exc), resource=resource)
        if exc.status_code == 400:
            return InvalidArgumentError(
                str(exc), details={"resource": resource} if resource else None
            )
        if exc.status_code in {500, 502, 503, 504}:
            return UnavailableError("storage backend", reason=str(exc))
    if isinstance(exc, AGFSPermissionDeniedError):
        return PermissionDeniedError(str(exc), resource=resource)
    if isinstance(exc, AGFSAlreadyExistsError):
        return ConflictError(str(exc), resource=resource)
    if isinstance(exc, AGFSNotSupportedError):
        return UnimplementedError(str(exc), details=_resource_details(resource))
    if isinstance(exc, AGFSInvalidPathError):
        message = str(exc)
        return InvalidURIError(resource or message, message)
    if isinstance(exc, (AGFSNotADirectoryError, NotADirectoryError)):
        return InvalidArgumentError(str(exc), details=_resource_details(resource))
    if isinstance(exc, (AGFSIsADirectoryError, IsADirectoryError)):
        return InvalidArgumentError(str(exc), details=_file_directory_details(resource))
    if isinstance(exc, AGFSDirectoryNotEmptyError):
        return InvalidArgumentError(str(exc), details=_resource_details(resource))
    if isinstance(exc, AGFSResourceExhaustedError):
        return ResourceExhaustedError(str(exc), details=_resource_details(resource))
    if isinstance(exc, AGFSInvalidOperationError):
        return InvalidArgumentError(str(exc), details=_resource_details(resource))
    if isinstance(exc, AGFSInternalError):
        return InternalError(str(exc))
    if isinstance(
        exc,
        (
            AGFSConfigError,
            AGFSIoError,
            AGFSMountPointNotFoundError,
            AGFSNetworkError,
            AGFSSerializationError,
        ),
    ):
        return UnavailableError("storage backend", reason=str(exc))
    if isinstance(exc, AGFSClientError):
        message = str(exc)
        if is_not_found_error(exc):
            return _not_found_error(resource, resource_type)
        if is_invalid_uri_error(exc):
            return InvalidURIError(resource or message, message)
        lowered = message.lower()
        if "not a directory" in lowered:
            return InvalidArgumentError(message, details=_resource_details(resource))
        if "is a directory" in lowered:
            return InvalidArgumentError(message, details=_resource_details(resource))
        if "directory not empty" in lowered:
            return InvalidArgumentError(message, details=_resource_details(resource))
        if "permission denied" in lowered:
            return PermissionDeniedError(message, resource=resource)
        if "already exists" in lowered:
            return ConflictError(message, resource=resource)
        if (
            "invalid operation" in lowered
            or "regex parse error" in lowered
            or "invalid regular expression" in lowered
        ):
            return InvalidArgumentError(message, details=_resource_details(resource))
        if (
            isinstance(exc, AGFSPluginError)
            or "timeout" in lowered
            or "connection refused" in lowered
        ):
            return UnavailableError("storage backend", reason=message)
    upstream_mapped = _map_upstream_api_error(exc)
    if upstream_mapped is not None:
        return upstream_mapped
    message = str(exc)
    lowered = message.lower()
    if is_not_found_error(exc):
        return _not_found_error(resource, resource_type)
    if is_invalid_uri_error(exc):
        return InvalidURIError(resource or message, message)
    if "permission denied" in lowered or "access denied" in lowered:
        return PermissionDeniedError(message, resource=resource)
    if "timeout" in lowered or "connection refused" in lowered:
        return UnavailableError("storage backend", reason=message)
    return None