Explain OAuth bucket write failures safely

Source commit: c290d348b11f29b480df28112b4c7558cc0fad1f

Dockerfile

@@ -9,7 +9,8 @@ RUN uv pip install --system --no-cache \
     fast-agent-mcp==0.9.27 \
     'fastmcp[apps]==3.4.4' \
     prefab-ui==0.20.2 \
-    huggingface_hub \
+    huggingface_hub==1.24.0 \
+    hf-xet==1.5.2 \
     pillow
 
 COPY --link ./ /app

research/research_workspace.py

@@ -6,20 +6,40 @@ import hashlib
 import json
 import os
 import re
+from collections.abc import Mapping
 from contextvars import ContextVar
 from dataclasses import dataclass
 from datetime import UTC, datetime
-from typing import Any, Mapping
+from typing import Any
 from uuid import uuid4
 
+from fast_agent import AgentAuth
+from fast_agent.mcp.server.common import normalize_serve_oauth_provider
 from huggingface_hub import HfApi, get_token
 from huggingface_hub.errors import BucketNotFoundError
 
-from fast_agent import AgentAuth
-from fast_agent.mcp.server.common import normalize_serve_oauth_provider
+_SAFE_SEGMENT = re.compile(r"[^A-Za-z0-9._-]+")
 
 
-_SAFE_SEGMENT = re.compile(r"[^A-Za-z0-9._-]+")
+class WorkspaceProvisionError(RuntimeError):
+    """Safe, user-facing workspace setup failure."""
+
+    code = "HF_WORKSPACE_PROVISION_FAILED"
+
+
+class WorkspaceWriteAuthorizationError(WorkspaceProvisionError):
+    """The caller can read the workspace bucket but cannot write to it."""
+
+    code = "HF_BUCKET_WRITE_NOT_AUTHORIZED"
+
+    def __init__(self) -> None:
+        super().__init__(
+            "Your Hugging Face connection can read the existing research workspace "
+            "but is not authorized to write to it. The `contribute-repos` permission "
+            "alone covers only Buckets created by the same OAuth app. Reconnect after "
+            "this app's requested write access is available, or use a new workspace "
+            "created by this app."
+        )
 
 
 @dataclass(frozen=True, slots=True)
@@ -104,8 +124,11 @@ def ensure_workspace(
                 token=token,
             )
         except Exception as exc:
-            raise RuntimeError(
-                f"Bucket {bucket_id!r} is accessible but marker write failed: {exc}"
+            if _is_xet_write_forbidden(exc):
+                raise WorkspaceWriteAuthorizationError from exc
+            raise WorkspaceProvisionError(
+                "The research workspace could not be initialized. Reconnect your "
+                "Hugging Face account and try again."
             ) from exc
         marker_paths = (
             f"{root}scratch/.workspace.json",
@@ -125,6 +148,14 @@ def ensure_workspace(
     )
 
 
+def _is_xet_write_forbidden(exc: BaseException) -> bool:
+    """Classify hf-xet 1.5.x's opaque write-token authorization failure."""
+    if not isinstance(exc, ConnectionError):
+        return False
+    detail = str(exc)
+    return "403 Forbidden" in detail and "/xet-write-token" in detail
+
+
 def _token(auth: AgentAuth | None) -> str | None:
     if auth is not None and auth.token:
         return auth.token