sysadminandClaude Opus 4.8
7e5eca08b3
Mutation tools (create_issue, create_pr, delete_branch, issue-lock) returned reason_code=internal_error / retryable=false with no class, message, HTTP status, or actionable detail. The #699/#701 tool-error boundary intentionally collapses every non-typed exception to a fixed "Internal tool error" and drops the class and message, so a mutation failure is undiagnosable — and the #695 runtime guard blocks standalone reproduction. The true failing stage was therefore invisible by two independent mechanisms. Make the failure observable and actionable without weakening the secret-free contract: - Boundary (internal_error path ONLY): capture a safe exception class (a Python type identifier, never instance text) plus a strictly-redacted `detail` (token/Authorization/Bearer credentials, JSON/kv secret values incl. short passwords, raw URLs/hostnames, and absolute filesystem paths all stripped; whitespace collapsed; length-bounded) and an optional `mutation_stage`. Typed auth/authz/network/config/http paths are unchanged and still emit no detail. - Convert raw exceptions into typed structured errors via a safe `gitea_reason_code` attribute contract: server raisers may self-declare a known reason and the boundary emits it (fixed message) instead of an opaque internal_error. Pre-flight order violations now raise `_PreflightOrderError` (a RuntimeError subclass → preflight_order_violation). - Add a `_mutation_stage` context manager tagging escaping exceptions with the stage name (preflight_purity / resolve_auth / api_*), applied to delete_branch, create_issue, create_pr. Fail-closed identity/repo/worktree/role/permission/lock/lease/ancestry gates are untouched; only error *reporting* changed. New suite test_mutation_error_diagnostics.py (18 tests) pins the redaction, class capture, stage tagging, typed conversion, and adversarial no-leak contract. Existing boundary suite (25), core server (209), and preflight (92) suites stay green. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
635 lines
24 KiB
Python
635 lines
24 KiB
Python
"""MCP tool-boundary error mapping for known Gitea client failures (#699).
|
|
|
|
Known authentication / authorization / network / configuration failures leave
|
|
the tool boundary as a sanitized structured ``CallToolResult`` with
|
|
``isError=True``. Stdio transport remains connected.
|
|
|
|
Design constraints (reviewer-ratified, #699 / PR #701):
|
|
|
|
1. **No secret material** in tool results or daemon logs. Messages are fixed
|
|
constants keyed by ``reason_code``; HTTP bodies / exception text never
|
|
surface. Sanitization failure fails closed to ``internal_error``.
|
|
2. **Narrow boundary** wraps the original FastMCP ``Tool.run`` success path;
|
|
re-raises framework control-flow exceptions (``UrlElicitationRequiredError``);
|
|
maps only typed client failures. Installation is idempotent.
|
|
3. **No RuntimeError substring heuristics.** Only explicit typed
|
|
authentication / authorization / network / configuration exceptions
|
|
receive those labels.
|
|
4. **HTTP classification** lives in ``gitea_auth.classify_http_status``;
|
|
every 403 is authorization-class.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
import logging
|
|
import re
|
|
import sys
|
|
from typing import Any
|
|
|
|
logger = logging.getLogger("gitea_mcp.tool_error_boundary")
|
|
|
|
# Stable reason codes (#699).
|
|
REASON_AUTH_FAILED = "auth_failed"
|
|
REASON_AUTH_INVALID_TOKEN = "auth_invalid_token"
|
|
REASON_AUTHZ_INSUFFICIENT_SCOPE = "authz_insufficient_scope"
|
|
REASON_AUTHZ_DENIED = "authz_denied"
|
|
REASON_NETWORK_ERROR = "network_error"
|
|
REASON_CONFIG_ERROR = "config_error"
|
|
REASON_INTERNAL_ERROR = "internal_error"
|
|
REASON_UPSTREAM_UNAVAILABLE = "upstream_unavailable"
|
|
REASON_HTTP_ERROR = "http_error"
|
|
# Typed structured errors for previously-opaque raw mutation failures.
|
|
REASON_PREFLIGHT_ORDER = "preflight_order_violation"
|
|
REASON_MALFORMED_RESPONSE = "malformed_response"
|
|
|
|
ERROR_CLASS_AUTHENTICATION = "authentication"
|
|
ERROR_CLASS_AUTHORIZATION = "authorization"
|
|
ERROR_CLASS_NETWORK = "network"
|
|
ERROR_CLASS_CONFIGURATION = "configuration"
|
|
ERROR_CLASS_INTERNAL = "internal"
|
|
ERROR_CLASS_UPSTREAM = "upstream"
|
|
ERROR_CLASS_PRECONDITION = "precondition"
|
|
|
|
# Fixed, secret-free operator messages. Never interpolate HTTP bodies,
|
|
# Keychain contents, tokens, or arbitrary exception text.
|
|
FIXED_MESSAGES: dict[str, str] = {
|
|
REASON_AUTH_FAILED: "Gitea authentication failed",
|
|
REASON_AUTH_INVALID_TOKEN: (
|
|
"Gitea authentication failed: invalid or revoked credentials"
|
|
),
|
|
REASON_AUTHZ_INSUFFICIENT_SCOPE: (
|
|
"Gitea authorization failed: insufficient token scope"
|
|
),
|
|
REASON_AUTHZ_DENIED: "Gitea authorization failed: access denied",
|
|
REASON_NETWORK_ERROR: "Network error contacting Gitea",
|
|
REASON_CONFIG_ERROR: "Gitea configuration or credential resolution failed",
|
|
REASON_INTERNAL_ERROR: "Internal tool error",
|
|
REASON_UPSTREAM_UNAVAILABLE: "Gitea upstream unavailable",
|
|
REASON_HTTP_ERROR: "Gitea HTTP request failed",
|
|
REASON_PREFLIGHT_ORDER: (
|
|
"Mutation blocked: pre-flight order violation (fail closed)"
|
|
),
|
|
REASON_MALFORMED_RESPONSE: "Malformed response from Gitea",
|
|
}
|
|
|
|
# Error class for a self-declared safe reason code (``gitea_reason_code``).
|
|
_REASON_ERROR_CLASS: dict[str, str] = {
|
|
REASON_AUTH_FAILED: ERROR_CLASS_AUTHENTICATION,
|
|
REASON_AUTH_INVALID_TOKEN: ERROR_CLASS_AUTHENTICATION,
|
|
REASON_AUTHZ_INSUFFICIENT_SCOPE: ERROR_CLASS_AUTHORIZATION,
|
|
REASON_AUTHZ_DENIED: ERROR_CLASS_AUTHORIZATION,
|
|
REASON_NETWORK_ERROR: ERROR_CLASS_NETWORK,
|
|
REASON_CONFIG_ERROR: ERROR_CLASS_CONFIGURATION,
|
|
REASON_UPSTREAM_UNAVAILABLE: ERROR_CLASS_UPSTREAM,
|
|
REASON_HTTP_ERROR: ERROR_CLASS_INTERNAL,
|
|
REASON_PREFLIGHT_ORDER: ERROR_CLASS_PRECONDITION,
|
|
REASON_MALFORMED_RESPONSE: ERROR_CLASS_INTERNAL,
|
|
REASON_INTERNAL_ERROR: ERROR_CLASS_INTERNAL,
|
|
}
|
|
|
|
# Bounds for the safe diagnostic fields added to the ``internal_error`` path.
|
|
_DETAIL_LIMIT = 200
|
|
_CLASS_LIMIT = 120
|
|
_STAGE_LIMIT = 64
|
|
|
|
# Absolute-path prefixes stripped from diagnostic detail (never leak layout).
|
|
_ABS_PATH_RE = re.compile(r"/(?:Users|home|private|var|tmp|opt|etc|root)/[^\s'\"]*")
|
|
_DETAIL_SECRET_PREFIXES = ("token ", "Basic ", "Bearer ", "Authorization: ")
|
|
_SECRET_KEY = (
|
|
r"token|password|passwd|secret|authorization|api[_-]?key|"
|
|
r"access[_-]?token|refresh[_-]?token|session|cookie"
|
|
)
|
|
_SECRET_JSON_RE = re.compile(
|
|
r'"(' + _SECRET_KEY + r')"\s*:\s*"[^"]*"', re.IGNORECASE
|
|
)
|
|
_SECRET_KV_RE = re.compile(
|
|
r"\b(" + _SECRET_KEY + r")\s*=\s*[^\s&\"']+", re.IGNORECASE
|
|
)
|
|
|
|
_MUTATION_STAGE_ATTR = "_gitea_mutation_stage"
|
|
_SELF_DECLARED_REASON_ATTR = "gitea_reason_code"
|
|
|
|
_INSTALL_FLAG = "_gitea_auth_boundary_installed"
|
|
_ORIGINAL_ATTR = "_gitea_auth_boundary_original"
|
|
|
|
|
|
def _safe_str(exc: BaseException) -> str:
|
|
"""``str(exc)`` that never raises (a poisoned ``__str__`` must not escape)."""
|
|
try:
|
|
return str(exc)
|
|
except Exception:
|
|
return ""
|
|
|
|
|
|
def _safe_exception_class(exc: BaseException) -> str:
|
|
"""Fully-qualified type identifier for *exc* — never instance/message text."""
|
|
try:
|
|
t = type(exc)
|
|
mod = getattr(t, "__module__", "") or ""
|
|
name = getattr(t, "__qualname__", None) or getattr(t, "__name__", "") or ""
|
|
ident = f"{mod}.{name}" if mod else name
|
|
return ident[:_CLASS_LIMIT]
|
|
except Exception:
|
|
return "unknown"
|
|
|
|
|
|
def _redact_detail(text: Any, limit: int = _DETAIL_LIMIT) -> str:
|
|
"""Strictly redact free-form exception text for safe diagnostics.
|
|
|
|
Removes token/Authorization credentials, raw URLs and hostnames (via the
|
|
shared audit redactor), and absolute filesystem paths, then collapses
|
|
whitespace and truncates. Never raises; on any failure returns "".
|
|
"""
|
|
if not text:
|
|
return ""
|
|
try:
|
|
out = str(text)
|
|
# Drop credential-prefixed runs (token/Basic/Bearer/Authorization).
|
|
for prefix in _DETAIL_SECRET_PREFIXES:
|
|
idx = 0
|
|
while True:
|
|
i = out.find(prefix, idx)
|
|
if i == -1:
|
|
break
|
|
j = i + len(prefix)
|
|
while j < len(out) and not out[j].isspace():
|
|
j += 1
|
|
out = out[:i] + prefix + "[REDACTED]" + out[j:]
|
|
idx = i + len(prefix) + len("[REDACTED]")
|
|
# Secret VALUES carried in JSON ("key":"value") or kv (key=value) form,
|
|
# even short ones (e.g. a password), keyed by a sensitive field name.
|
|
out = _SECRET_JSON_RE.sub(r'"\1":"[REDACTED]"', out)
|
|
out = _SECRET_KV_RE.sub(r"\1=[REDACTED]", out)
|
|
# URLs / query secrets / hostnames.
|
|
try:
|
|
import gitea_audit
|
|
|
|
out = gitea_audit.redact_urls(out)
|
|
except Exception:
|
|
pass
|
|
# Absolute filesystem paths (workspace layout is not for LLM output).
|
|
out = _ABS_PATH_RE.sub("[PATH]", out)
|
|
# Any bare hostname the URL redactor missed (defence in depth).
|
|
out = re.sub(r"\b[\w.-]+\.(?:cc|net|com|org|io|dev|local)\b", "[HOST]", out)
|
|
out = " ".join(out.split())
|
|
return out[:limit]
|
|
except Exception:
|
|
return ""
|
|
|
|
|
|
def _safe_mutation_stage(exc: BaseException) -> str | None:
|
|
"""Return the bounded, redacted mutation stage tagged on *exc* (or None)."""
|
|
try:
|
|
raw = getattr(exc, _MUTATION_STAGE_ATTR, None)
|
|
if not raw:
|
|
return None
|
|
return _redact_detail(raw, limit=_STAGE_LIMIT) or None
|
|
except Exception:
|
|
return None
|
|
|
|
|
|
def fixed_message(reason_code: str) -> str:
|
|
"""Return the fixed sanitized message for *reason_code* (fail closed)."""
|
|
return FIXED_MESSAGES.get(reason_code, FIXED_MESSAGES[REASON_INTERNAL_ERROR])
|
|
|
|
|
|
def _safe_profile_name() -> str | None:
|
|
try:
|
|
from gitea_auth import get_profile
|
|
|
|
name = (get_profile() or {}).get("profile_name")
|
|
if name is None:
|
|
return None
|
|
text = str(name).strip()
|
|
# Profile names are non-secret identifiers; still bound length.
|
|
return text[:80] if text else None
|
|
except Exception:
|
|
return None
|
|
|
|
|
|
def _is_framework_control_flow(exc: BaseException) -> bool:
|
|
"""True for exceptions the MCP framework must re-raise unchanged."""
|
|
try:
|
|
from mcp.shared.exceptions import UrlElicitationRequiredError
|
|
|
|
if isinstance(exc, UrlElicitationRequiredError):
|
|
return True
|
|
except Exception:
|
|
pass
|
|
# BaseException subclasses that must never become tool isError payloads.
|
|
if isinstance(exc, (KeyboardInterrupt, SystemExit, GeneratorExit)):
|
|
return True
|
|
return False
|
|
|
|
|
|
def is_known_client_failure(exc: BaseException) -> bool:
|
|
"""True only for explicit typed Gitea client / config failures.
|
|
|
|
Never true for arbitrary ``RuntimeError`` (reviewer finding #3).
|
|
"""
|
|
try:
|
|
import gitea_auth
|
|
|
|
if isinstance(
|
|
exc,
|
|
(
|
|
gitea_auth.GiteaAuthError,
|
|
gitea_auth.GiteaAuthzError,
|
|
gitea_auth.GiteaNetworkError,
|
|
gitea_auth.GiteaConfigError,
|
|
gitea_auth.GiteaHttpError,
|
|
),
|
|
):
|
|
return True
|
|
except Exception:
|
|
return False
|
|
try:
|
|
import gitea_config
|
|
|
|
if isinstance(exc, gitea_config.ConfigError):
|
|
return True
|
|
except Exception:
|
|
pass
|
|
return False
|
|
|
|
|
|
def classify_exception(exc: BaseException) -> dict[str, Any]:
|
|
"""Return structured classification with **fixed** messages only.
|
|
|
|
Only typed authentication / authorization / network / configuration
|
|
failures receive those labels. Unexpected programming failures are
|
|
``internal_error``. HTTP bodies and exception text are never copied
|
|
into ``message``.
|
|
"""
|
|
try:
|
|
return _classify_exception_impl(exc)
|
|
except Exception:
|
|
# Fail closed: sanitization / classification failure must not leak.
|
|
return {
|
|
"reason_code": REASON_INTERNAL_ERROR,
|
|
"error_class": ERROR_CLASS_INTERNAL,
|
|
"http_status": None,
|
|
"message": fixed_message(REASON_INTERNAL_ERROR),
|
|
"transport_survives": True,
|
|
}
|
|
|
|
|
|
def _self_declared_classification(exc: BaseException) -> dict[str, Any] | None:
|
|
"""Honor a safe ``gitea_reason_code`` attribute set by server-side raisers.
|
|
|
|
Converts a raw exception that self-declares a **known** reason code into a
|
|
typed structured error (fixed message) instead of an opaque internal_error.
|
|
Unknown / non-string / secret values are ignored (fail closed to internal).
|
|
"""
|
|
reason = getattr(exc, _SELF_DECLARED_REASON_ATTR, None)
|
|
if not isinstance(reason, str) or reason not in FIXED_MESSAGES:
|
|
return None
|
|
if reason == REASON_INTERNAL_ERROR:
|
|
return None
|
|
return {
|
|
"reason_code": reason,
|
|
"error_class": _REASON_ERROR_CLASS.get(reason, ERROR_CLASS_INTERNAL),
|
|
"http_status": None,
|
|
"message": fixed_message(reason),
|
|
"transport_survives": True,
|
|
}
|
|
|
|
|
|
def _classify_exception_impl(exc: BaseException) -> dict[str, Any]:
|
|
import gitea_auth
|
|
|
|
declared = _self_declared_classification(exc)
|
|
if declared is not None:
|
|
return declared
|
|
|
|
if isinstance(exc, gitea_auth.GiteaAuthError):
|
|
code = getattr(exc, "reason_code", None) or REASON_AUTH_INVALID_TOKEN
|
|
if code not in (
|
|
REASON_AUTH_FAILED,
|
|
REASON_AUTH_INVALID_TOKEN,
|
|
):
|
|
code = REASON_AUTH_INVALID_TOKEN
|
|
return {
|
|
"reason_code": code,
|
|
"error_class": ERROR_CLASS_AUTHENTICATION,
|
|
"http_status": getattr(exc, "http_status", None) or 401,
|
|
"message": fixed_message(code),
|
|
"transport_survives": True,
|
|
}
|
|
if isinstance(exc, gitea_auth.GiteaAuthzError):
|
|
code = getattr(exc, "reason_code", None) or REASON_AUTHZ_DENIED
|
|
if code not in (REASON_AUTHZ_DENIED, REASON_AUTHZ_INSUFFICIENT_SCOPE):
|
|
code = REASON_AUTHZ_DENIED
|
|
return {
|
|
"reason_code": code,
|
|
"error_class": ERROR_CLASS_AUTHORIZATION,
|
|
"http_status": getattr(exc, "http_status", None) or 403,
|
|
"message": fixed_message(code),
|
|
"transport_survives": True,
|
|
}
|
|
if isinstance(exc, gitea_auth.GiteaNetworkError):
|
|
return {
|
|
"reason_code": REASON_NETWORK_ERROR,
|
|
"error_class": ERROR_CLASS_NETWORK,
|
|
"http_status": getattr(exc, "http_status", None),
|
|
"message": fixed_message(REASON_NETWORK_ERROR),
|
|
"transport_survives": True,
|
|
}
|
|
if isinstance(exc, gitea_auth.GiteaConfigError):
|
|
return {
|
|
"reason_code": REASON_CONFIG_ERROR,
|
|
"error_class": ERROR_CLASS_CONFIGURATION,
|
|
"http_status": getattr(exc, "http_status", None),
|
|
"message": fixed_message(REASON_CONFIG_ERROR),
|
|
"transport_survives": True,
|
|
}
|
|
if isinstance(exc, gitea_auth.GiteaHttpError):
|
|
code = getattr(exc, "reason_code", None) or REASON_HTTP_ERROR
|
|
if code == REASON_UPSTREAM_UNAVAILABLE:
|
|
error_class = ERROR_CLASS_UPSTREAM
|
|
else:
|
|
error_class = ERROR_CLASS_INTERNAL
|
|
code = REASON_HTTP_ERROR
|
|
return {
|
|
"reason_code": code,
|
|
"error_class": error_class,
|
|
"http_status": getattr(exc, "http_status", None),
|
|
"message": fixed_message(code),
|
|
"transport_survives": True,
|
|
}
|
|
|
|
try:
|
|
import gitea_config
|
|
|
|
if isinstance(exc, gitea_config.ConfigError):
|
|
return {
|
|
"reason_code": REASON_CONFIG_ERROR,
|
|
"error_class": ERROR_CLASS_CONFIGURATION,
|
|
"http_status": None,
|
|
"message": fixed_message(REASON_CONFIG_ERROR),
|
|
"transport_survives": True,
|
|
}
|
|
except Exception:
|
|
pass
|
|
|
|
# Unwrap FastMCP ToolError cause when the original was a typed failure.
|
|
cause = getattr(exc, "__cause__", None)
|
|
if cause is not None and cause is not exc and is_known_client_failure(cause):
|
|
return _classify_exception_impl(cause)
|
|
|
|
# No message-substring authentication heuristics (reviewer finding #3).
|
|
# Unexpected failure → internal_error, now carrying SAFE diagnostics so the
|
|
# failure is actionable: a type identifier + strictly-redacted detail +
|
|
# optional mutation-stage tag. The operator ``message`` stays the fixed
|
|
# constant; none of these fields carry secrets/bodies/paths/env.
|
|
result = {
|
|
"reason_code": REASON_INTERNAL_ERROR,
|
|
"error_class": ERROR_CLASS_INTERNAL,
|
|
"http_status": None,
|
|
"message": fixed_message(REASON_INTERNAL_ERROR),
|
|
"transport_survives": True,
|
|
"exception_class": _safe_exception_class(exc),
|
|
"detail": _redact_detail(_safe_str(exc)),
|
|
}
|
|
stage = _safe_mutation_stage(exc)
|
|
if stage:
|
|
result["mutation_stage"] = stage
|
|
return result
|
|
|
|
|
|
def build_structured_error_payload(
|
|
classification: dict[str, Any],
|
|
*,
|
|
tool_name: str | None = None,
|
|
profile_name: str | None = None,
|
|
) -> dict[str, Any]:
|
|
"""LLM-safe structured payload — fixed message + typed metadata only."""
|
|
try:
|
|
reason = str(classification.get("reason_code") or REASON_INTERNAL_ERROR)
|
|
message = fixed_message(reason)
|
|
# Refuse to emit any classification message that is not the fixed constant.
|
|
if classification.get("message") != message:
|
|
message = fixed_message(reason)
|
|
payload: dict[str, Any] = {
|
|
"success": False,
|
|
"isError": True,
|
|
"reason_code": reason if reason in FIXED_MESSAGES else REASON_INTERNAL_ERROR,
|
|
"error_class": classification.get("error_class") or ERROR_CLASS_INTERNAL,
|
|
"message": message,
|
|
"transport_survives": True,
|
|
"retryable": classification.get("error_class")
|
|
in {
|
|
ERROR_CLASS_AUTHENTICATION,
|
|
ERROR_CLASS_NETWORK,
|
|
ERROR_CLASS_CONFIGURATION,
|
|
},
|
|
}
|
|
status = classification.get("http_status")
|
|
if isinstance(status, int):
|
|
payload["http_status"] = status
|
|
if tool_name and isinstance(tool_name, str):
|
|
# Tool names are identifiers, not secrets; bound length.
|
|
payload["tool"] = tool_name[:120]
|
|
if profile_name and isinstance(profile_name, str):
|
|
payload["profile"] = profile_name[:80]
|
|
# Safe diagnostics — internal_error path only. These make an otherwise
|
|
# opaque crash actionable without leaking secrets. Re-derived here from
|
|
# the fixed message gate above; typed reasons never carry them.
|
|
if payload["reason_code"] == REASON_INTERNAL_ERROR:
|
|
exc_cls = classification.get("exception_class")
|
|
if isinstance(exc_cls, str) and exc_cls:
|
|
payload["exception_class"] = exc_cls[:_CLASS_LIMIT]
|
|
detail = classification.get("detail")
|
|
if isinstance(detail, str):
|
|
payload["detail"] = _redact_detail(detail)
|
|
stage = classification.get("mutation_stage")
|
|
if isinstance(stage, str) and stage:
|
|
payload["mutation_stage"] = stage[:_STAGE_LIMIT]
|
|
return payload
|
|
except Exception:
|
|
return {
|
|
"success": False,
|
|
"isError": True,
|
|
"reason_code": REASON_INTERNAL_ERROR,
|
|
"error_class": ERROR_CLASS_INTERNAL,
|
|
"message": fixed_message(REASON_INTERNAL_ERROR),
|
|
"transport_survives": True,
|
|
"retryable": False,
|
|
}
|
|
|
|
|
|
def log_sanitized_daemon_reason(
|
|
classification: dict[str, Any],
|
|
*,
|
|
tool_name: str | None = None,
|
|
stream=None,
|
|
) -> None:
|
|
"""Daemon log: reason codes only — never exception text or response bodies."""
|
|
stream = stream if stream is not None else sys.stderr
|
|
try:
|
|
reason = classification.get("reason_code") or REASON_INTERNAL_ERROR
|
|
error_class = classification.get("error_class") or ERROR_CLASS_INTERNAL
|
|
# Only emit known tokens; never classification['message'] from callers
|
|
# that might have been poisoned.
|
|
if reason not in FIXED_MESSAGES:
|
|
reason = REASON_INTERNAL_ERROR
|
|
error_class = ERROR_CLASS_INTERNAL
|
|
parts = [
|
|
"mcp_tool_error",
|
|
f"reason_code={reason}",
|
|
f"error_class={error_class}",
|
|
]
|
|
if tool_name and isinstance(tool_name, str):
|
|
parts.append(f"tool={tool_name[:120]}")
|
|
status = classification.get("http_status")
|
|
if isinstance(status, int):
|
|
parts.append(f"http_status={status}")
|
|
# Safe diagnostics — internal_error path ONLY. Typed reasons still emit
|
|
# no detail= (secrets lived there). class/detail/stage are re-redacted
|
|
# here as defence in depth.
|
|
if reason == REASON_INTERNAL_ERROR:
|
|
exc_cls = classification.get("exception_class")
|
|
if isinstance(exc_cls, str) and exc_cls:
|
|
parts.append(f"exception_class={exc_cls[:_CLASS_LIMIT]}")
|
|
stage = classification.get("mutation_stage")
|
|
if isinstance(stage, str) and stage:
|
|
parts.append(
|
|
f"mutation_stage={_redact_detail(stage, limit=_STAGE_LIMIT)}"
|
|
)
|
|
detail = classification.get("detail")
|
|
if isinstance(detail, str) and detail:
|
|
parts.append(f"detail={_redact_detail(detail)}")
|
|
line = " ".join(parts)
|
|
stream.write(line + "\n")
|
|
if hasattr(stream, "flush"):
|
|
stream.flush()
|
|
logger.warning(line)
|
|
except Exception:
|
|
# Fail closed: never fall back to logging the exception.
|
|
try:
|
|
stream.write(
|
|
"mcp_tool_error reason_code=internal_error "
|
|
"error_class=internal\n"
|
|
)
|
|
if hasattr(stream, "flush"):
|
|
stream.flush()
|
|
except Exception:
|
|
pass
|
|
|
|
|
|
def to_call_tool_result(
|
|
exc: BaseException,
|
|
*,
|
|
tool_name: str | None = None,
|
|
profile_name: str | None = None,
|
|
log: bool = True,
|
|
) -> Any:
|
|
"""Build a FastMCP ``CallToolResult`` with ``isError=True`` for *exc*."""
|
|
from mcp.types import CallToolResult, TextContent
|
|
|
|
try:
|
|
classification = classify_exception(exc)
|
|
if log:
|
|
log_sanitized_daemon_reason(classification, tool_name=tool_name)
|
|
payload = build_structured_error_payload(
|
|
classification, tool_name=tool_name, profile_name=profile_name
|
|
)
|
|
text = json.dumps(payload, indent=2, sort_keys=True)
|
|
return CallToolResult(
|
|
content=[TextContent(type="text", text=text)],
|
|
structuredContent=payload,
|
|
isError=True,
|
|
)
|
|
except Exception:
|
|
# Absolute fail-closed path — no exception text.
|
|
fallback = {
|
|
"success": False,
|
|
"isError": True,
|
|
"reason_code": REASON_INTERNAL_ERROR,
|
|
"error_class": ERROR_CLASS_INTERNAL,
|
|
"message": fixed_message(REASON_INTERNAL_ERROR),
|
|
"transport_survives": True,
|
|
"retryable": False,
|
|
}
|
|
return CallToolResult(
|
|
content=[
|
|
TextContent(
|
|
type="text",
|
|
text=json.dumps(fallback, indent=2, sort_keys=True),
|
|
)
|
|
],
|
|
structuredContent=fallback,
|
|
isError=True,
|
|
)
|
|
|
|
|
|
def install_tool_run_boundary(Tool) -> bool:
|
|
"""Install a **narrow** error boundary around FastMCP ``Tool.run``.
|
|
|
|
Strategy (preserves framework semantics):
|
|
|
|
* Call the **original** ``Tool.run`` for the success path (async, return
|
|
types, convert_result, protocol behavior unchanged).
|
|
* Re-raise ``UrlElicitationRequiredError`` and other control-flow
|
|
exceptions without mapping to ``internal_error``.
|
|
* Map typed Gitea client failures (and ToolError whose ``__cause__`` is
|
|
typed) to structured ``CallToolResult(isError=True)``.
|
|
* Map remaining unexpected tool failures to fixed ``internal_error``
|
|
isError results (transport survival) without secret-bearing text.
|
|
* Idempotent: second install is a no-op and returns ``False``.
|
|
"""
|
|
if getattr(Tool.run, _INSTALL_FLAG, False):
|
|
return False
|
|
|
|
from mcp.server.fastmcp.exceptions import ToolError
|
|
from mcp.shared.exceptions import UrlElicitationRequiredError
|
|
|
|
original_run = Tool.run
|
|
|
|
async def run_boundary(
|
|
self,
|
|
arguments: dict[str, Any],
|
|
context=None,
|
|
convert_result: bool = False,
|
|
) -> Any:
|
|
try:
|
|
return await original_run(
|
|
self,
|
|
arguments,
|
|
context=context,
|
|
convert_result=convert_result,
|
|
)
|
|
except UrlElicitationRequiredError:
|
|
# Framework control-flow — must not become internal_error.
|
|
raise
|
|
except BaseException as exc:
|
|
if _is_framework_control_flow(exc):
|
|
raise
|
|
if not isinstance(exc, Exception):
|
|
raise
|
|
|
|
# Prefer typed cause under FastMCP ToolError wrappers.
|
|
target: BaseException = exc
|
|
if isinstance(exc, ToolError) and exc.__cause__ is not None:
|
|
target = exc.__cause__
|
|
|
|
# Known client failures → structured isError with reason codes.
|
|
# Unexpected failures → fixed internal_error isError (no secrets).
|
|
profile_name = _safe_profile_name()
|
|
return to_call_tool_result(
|
|
target,
|
|
tool_name=getattr(self, "name", None),
|
|
profile_name=profile_name,
|
|
)
|
|
|
|
setattr(run_boundary, _INSTALL_FLAG, True)
|
|
setattr(run_boundary, _ORIGINAL_ATTR, original_run)
|
|
Tool.run = run_boundary # type: ignore[method-assign]
|
|
return True
|
|
|
|
|
|
def boundary_is_installed(Tool) -> bool:
|
|
"""True when the #699 boundary is active on *Tool.run*."""
|
|
return bool(getattr(Tool.run, _INSTALL_FLAG, False))
|