refactored update bluesky profile tool

tools/bluesky/update_bluesky_profile.py

···
 
 import os
 from typing import Optional
+from atproto import Client, models
+
 
 def update_bluesky_profile(display_name: Optional[str] = None, bio: Optional[str] = None) -> dict:
     """
-    Safely update the user's Bluesky profile display name and/or bio
-    without losing other fields (avatar, banner, etc.).
+    Update the authenticated user's Bluesky profile display name and/or bio.
+
+    This tool safely updates profile information while automatically preserving all other
+    profile data (avatar, banner, pinned post, etc.). You can confidently update just the
+    display name, just the bio, or both together - the tool handles preserving unchanged
+    fields for you.
+
+    The tool uses a safe fetch-merge-write pattern: it retrieves the current profile,
+    merges your updates with existing data, then saves the complete record. This ensures
+    no data loss when updating individual fields.
+
+    Use this tool when you need to update the user's display name, bio, or both. Updates
+    are immediate and visible on the user's profile.
 
     Args:
-        display_name: The new display name for the profile (max 64 characters). Optional
-        bio: The new bio/description for the profile (max 256 characters). Optional
+        display_name (Optional[str]): The new display name for the profile (max 64 characters). This is the prominent name shown on posts and the profile page. Can include Unicode characters, emoji, and special characters. Use empty string to remove the display name. If None, the current display name is preserved unchanged. Defaults to None.
+        bio (Optional[str]): The new bio/description for the profile (max 256 characters). This appears below the display name and profile picture. Can include line breaks, emoji, and special characters. Supports plain text only (no markdown). Use empty string to remove the bio. If None, the current bio is preserved unchanged. Defaults to None. At least one of display_name or bio must be provided (not both None).
 
     Returns:
-        A dictionary containing the status, success message, updated fields, and profile URL
+        dict: A dictionary containing the operation result with the following keys:
+
+            On success:
+            - status (str): "success"
+            - message (str): Confirmation message
+            - updated_fields (dict): The fields that were changed with their new values:
+                - displayName (str): New display name if updated
+                - description (str): New bio if updated
+            - profile_url (str): URL to view the updated profile on bsky.app
+
+            On error:
+            - status (str): "error"
+            - message (str): Human-readable error description with resolution guidance
+
+    Examples:
+        # Update only the display name
+        update_bluesky_profile(display_name="Alice Johnson")
+
+        # Update only the bio
+        update_bluesky_profile(bio="Software engineer interested in AI")
+
+        # Update both display name and bio
+        update_bluesky_profile(
+            display_name="Dr. Alice Johnson",
+            bio="Researcher in distributed systems and AI"
+        )
+
+        # Remove display name (use empty string)
+        update_bluesky_profile(display_name="")
+
+        # Update bio with multiple lines and emoji
+        update_bluesky_profile(
+            bio="🚀 Building the decentralized web\\nPreviously @BigTech\\n📍 San Francisco"
+        )
     """
     try:
-        from atproto import Client, models
-
         # Validate input
         if display_name is None and bio is None:
-            raise ValueError("At least one of display_name or bio must be provided.")
+            return {
+                "status": "error",
+                "message": "Error: No fields provided for update. To resolve this, provide at least one field to update: "
+                           "either display_name, bio, or both. You cannot call this tool with both parameters as None. "
+                           "This is a common mistake and can be fixed by specifying which field(s) you want to update."
+            }
+
         if display_name is not None and len(display_name) > 64:
-            raise ValueError("Display name exceeds 64 characters.")
+            return {
+                "status": "error",
+                "message": f"Error: The display_name is too long (current length: {len(display_name)} characters). "
+                           f"To resolve this, shorten it to 64 characters or less (you need to remove "
+                           f"{len(display_name) - 64} characters). This is a Bluesky platform limitation that applies "
+                           f"to all users. Consider making the name more concise."
+            }
+
         if bio is not None and len(bio) > 256:
-            raise ValueError("Bio exceeds 256 characters.")
+            return {
+                "status": "error",
+                "message": f"Error: The bio is too long (current length: {len(bio)} characters). To resolve this, "
+                           f"shorten it to 256 characters or less (you need to remove {len(bio) - 256} characters). "
+                           f"This is a Bluesky platform limitation that applies to all users. Consider making the "
+                           f"bio more concise or breaking it into shorter sentences."
+            }
 
         username = os.environ.get("BSKY_USERNAME")
         password = os.environ.get("BSKY_APP_PASSWORD")
         if not username or not password:
-            raise EnvironmentError("BSKY_USERNAME and BSKY_APP_PASSWORD environment variables must be set.")
+            return {
+                "status": "error",
+                "message": "Error: Missing Bluesky authentication credentials. The BSKY_USERNAME and BSKY_APP_PASSWORD "
+                           "environment variables are not set. To resolve this, ask the user to configure these environment "
+                           "variables with valid Bluesky credentials. This is a configuration issue that the user needs to "
+                           "address before you can update their profile."
+            }
 
         # Initialize client and login
         client = Client()
         client.login(username, password)
 
-        # ✅ Use the proper parameter model for get_record
-        params = models.ComAtprotoRepoGetRecord.Params(
-            repo=client.me.did,
-            collection="app.bsky.actor.profile",
-            rkey="self"
-        )
-        record = client.com.atproto.repo.get_record(params)
-        current_record = record.value
+        # STEP 1A: Fetch current profile via get_profile (reliable for display name and bio)
+        try:
+            current_profile = client.get_profile(actor=client.me.did)
+        except Exception as e:
+            return {
+                "status": "error",
+                "message": f"Error: Failed to fetch current profile via AppView. To resolve this, verify you are authenticated "
+                           f"and try again. This error can occur due to authentication issues or temporary API problems. "
+                           f"API details: {str(e)}"
+            }
+
+        # Extract current display name and bio from profile
+        current_display_name = getattr(current_profile, 'display_name', None) or ""
+        current_bio = getattr(current_profile, 'description', None) or ""
+
+        # STEP 1B: Fetch the complete raw profile record (for avatar, banner, etc.)
+        # This gets ALL fields from the repository that we need to preserve
+        try:
+            params = models.ComAtprotoRepoGetRecord.Params(
+                repo=client.me.did,
+                collection="app.bsky.actor.profile",
+                rkey="self"
+            )
+            record = client.com.atproto.repo.get_record(params)
+            current_record = record.value
+        except Exception as e:
+            return {
+                "status": "error",
+                "message": f"Error: Failed to fetch current profile record. To resolve this, verify you are authenticated "
+                           f"and try again. This error can occur due to authentication issues or temporary API problems. "
+                           f"API details: {str(e)}"
+            }
 
         # Convert model to dict if needed
         if not isinstance(current_record, dict):
···
             except Exception:
                 current_record = current_record.__dict__
 
-        # Merge updates
+        # STEP 2: Merge the updates into the existing record
+        # Use values from get_profile for fields not being updated (most reliable source)
+        # Start with the raw record to preserve avatar, banner, etc.
         updated_record = dict(current_record)
+
+        # For display name: use provided value, or fallback to current from get_profile
         if display_name is not None:
             updated_record["displayName"] = display_name
+        else:
+            # Ensure we keep the current display name from get_profile
+            updated_record["displayName"] = current_display_name
+
+        # For bio: use provided value, or fallback to current from get_profile
         if bio is not None:
             updated_record["description"] = bio
+        else:
+            # Ensure we keep the current bio from get_profile
+            updated_record["description"] = current_bio
 
-        # Ensure type field exists
+        # Ensure the record type field exists (required by AT Protocol)
         updated_record["$type"] = "app.bsky.actor.profile"
 
-        # ✅ Put updated record back using correct model
-        put_data = models.ComAtprotoRepoPutRecord.Data(
-            repo=client.me.did,
-            collection="app.bsky.actor.profile",
-            rkey="self",
-            record=updated_record
-        )
-        client.com.atproto.repo.put_record(put_data)
+        # STEP 3: Write the complete updated record back to Bluesky
+        # AT Protocol requires sending the entire record, not just changed fields
+        try:
+            put_data = models.ComAtprotoRepoPutRecord.Data(
+                repo=client.me.did,
+                collection="app.bsky.actor.profile",
+                rkey="self",
+                record=updated_record
+            )
+            client.com.atproto.repo.put_record(put_data)
+        except Exception as e:
+            return {
+                "status": "error",
+                "message": f"Error: Failed to update profile on Bluesky. To resolve this, verify your credentials are valid "
+                           f"and try again. This error can occur due to authentication issues, network problems, or temporary "
+                           f"API issues, and usually succeeds on retry. API details: {str(e)}"
+            }
 
         # Build structured success response
         updates = {}
···
         }
 
     except ImportError:
-        raise ImportError("atproto package not installed. Install it with: pip install atproto")
+        return {
+            "status": "error",
+            "message": "Error: The atproto Python package is not installed in the execution environment. "
+                       "To resolve this, the system administrator needs to install it using 'pip install atproto'. "
+                       "This is a dependency issue that prevents the tool from connecting to Bluesky. Once the "
+                       "package is installed, this tool will work normally."
+        }
     except Exception as e:
-        raise RuntimeError(f"Error updating Bluesky profile: {e}")
+        return {
+            "status": "error",
+            "message": f"Error: An unexpected issue occurred while updating the profile: {str(e)}. To resolve this, "
+                       f"verify your credentials are correct, ensure the display_name and bio meet length requirements, "
+                       f"and try again. This type of error is uncommon but can usually be resolved by retrying or "
+                       f"checking that your parameters are valid."
+        }