Add Gmail archive/label operations to gog capability

Co-Authored-By: GPT-5 Codex <codex@openai.com>

Author: dcramer

src/ash/integrations/skills/capabilities/google/SKILL.md

@@ -112,6 +112,8 @@ ash-sb capability invoke -c gog.email -o list_messages --account work --input-js
 ash-sb capability invoke -c gog.email -o search_messages --account work --input-json '{"query":"is:unread newer_than:1d","limit":20}'
 ash-sb capability invoke -c gog.email -o get_message --account work --input-json '{"id":"<message_id>"}'
 ash-sb capability invoke -c gog.email -o get_thread --account work --input-json '{"thread_id":"<thread_id>","limit":20}'
+ash-sb capability invoke -c gog.email -o archive_messages --account work --input-json '{"ids":["<message_id>"],"archive":true}'
+ash-sb capability invoke -c gog.email -o update_labels --account work --input-json '{"ids":["<message_id>"],"add_label_ids":["IMPORTANT"],"remove_label_ids":[]}'
 ash-sb capability invoke -c gog.calendar -o list_events --account work --input-json '{"calendar":"primary","window":"1d"}'
 ash-sb capability invoke -c gog.calendar -o create_event --account work --input-json '{"title":"Team sync","start":"2026-03-04T18:00:00Z"}'
 ```
@@ -148,11 +150,12 @@ Use Google calendar + Google email only for this view.
 
 ### Standard mutations
 
-Before `send_message` or `create_event`, confirm key details if user intent is ambiguous.
+Before `send_message`, `create_event`, `archive_messages`, or `update_labels`, always confirm key details.
 Required confirmation fields:
 
 - Email send: recipient, subject, body intent
 - Event create: title, start time/date, end time or duration, timezone context if unclear
+- Archive/update labels: target account alias, message IDs (or clearly identified messages), and the exact label/archive action
 
 ## Output Rules
 

src/ash/skills/bundled/gog/scripts/gogcli_bridge.py

@@ -89,6 +89,7 @@
     "gog.email": (
         "https://www.googleapis.com/auth/gmail.readonly"
         " https://www.googleapis.com/auth/gmail.send"
+        " https://www.googleapis.com/auth/gmail.modify"
     ),
     "gog.calendar": "https://www.googleapis.com/auth/calendar",
 }
@@ -449,7 +450,10 @@ def _google_api_request(
         request.add_header("Content-Type", "application/json")
     try:
         with urlopen(request, timeout=30) as resp:  # noqa: S310
-            return json.loads(resp.read().decode("utf-8"))
+            raw_body = resp.read().decode("utf-8").strip()
+            if not raw_body:
+                return {}
+            return json.loads(raw_body)
     except HTTPError as e:
         if e.code == 401:
             raise BridgeError(
@@ -728,6 +732,18 @@ def _handle_definitions() -> dict[str, Any]:
                         "requires_auth": True,
                         "mutating": True,
                     },
+                    {
+                        "name": "archive_messages",
+                        "description": "Archive or unarchive one or more messages",
+                        "requires_auth": True,
+                        "mutating": True,
+                    },
+                    {
+                        "name": "update_labels",
+                        "description": "Add/remove labels on one or more messages",
+                        "requires_auth": True,
+                        "mutating": True,
+                    },
                 ],
             },
             {
@@ -1427,6 +1443,20 @@ def _invoke_operation(
             account_ref=account_ref,
         )
 
+    if capability_id == "gog.email" and operation == "archive_messages":
+        return _invoke_archive_messages(
+            input_data=input_data,
+            access_token=access_token,
+            account_ref=account_ref,
+        )
+
+    if capability_id == "gog.email" and operation == "update_labels":
+        return _invoke_update_labels(
+            input_data=input_data,
+            access_token=access_token,
+            account_ref=account_ref,
+        )
+
     if capability_id == "gog.calendar" and operation == "list_events":
         return _invoke_list_events(
             input_data=input_data,
@@ -1888,6 +1918,157 @@ def _invoke_send_message(
     }
 
 
+def _required_string_list(
+    value: Any,
+    *,
+    field_name: str,
+    max_items: int,
+    allow_empty: bool = False,
+) -> list[str]:
+    if value is None:
+        values: list[Any] = []
+    elif isinstance(value, list):
+        values = value
+    else:
+        raise BridgeError("capability_invalid_input", f"{field_name} must be a list")
+
+    result: list[str] = []
+    seen: set[str] = set()
+    for item in values:
+        text = _optional_text(item)
+        if not text:
+            raise BridgeError(
+                "capability_invalid_input",
+                f"{field_name} entries must be non-empty strings",
+            )
+        if text in seen:
+            continue
+        seen.add(text)
+        result.append(text)
+
+    if not allow_empty and not result:
+        raise BridgeError("capability_invalid_input", f"{field_name} is required")
+    if len(result) > max_items:
+        raise BridgeError(
+            "capability_invalid_input",
+            f"{field_name} must contain at most {max_items} items",
+        )
+    return result
+
+
+def _gmail_modify_messages(
+    *,
+    access_token: str,
+    ids: list[str],
+    add_label_ids: list[str],
+    remove_label_ids: list[str],
+) -> None:
+    gmail_base = _google_gmail_api_base_url()
+    payload: dict[str, Any] = {}
+    if add_label_ids:
+        payload["addLabelIds"] = add_label_ids
+    if remove_label_ids:
+        payload["removeLabelIds"] = remove_label_ids
+
+    if len(ids) == 1:
+        _google_api_request(
+            "POST",
+            f"{gmail_base}/gmail/v1/users/me/messages/{ids[0]}/modify",
+            access_token=access_token,
+            json_body=payload,
+        )
+        return
+
+    _google_api_request(
+        "POST",
+        f"{gmail_base}/gmail/v1/users/me/messages/batchModify",
+        access_token=access_token,
+        json_body={**payload, "ids": ids},
+    )
+
+
+def _invoke_archive_messages(
+    *,
+    input_data: dict[str, Any],
+    access_token: str,
+    account_ref: str,
+) -> dict[str, Any]:
+    ids = _required_string_list(
+        input_data.get("ids"),
+        field_name="ids",
+        max_items=100,
+    )
+    raw_archive = input_data.get("archive", True)
+    if not isinstance(raw_archive, bool):
+        raise BridgeError("capability_invalid_input", "archive must be a boolean")
+    archive = raw_archive
+
+    add_label_ids = [] if archive else ["INBOX"]
+    remove_label_ids = ["INBOX"] if archive else []
+    _gmail_modify_messages(
+        access_token=access_token,
+        ids=ids,
+        add_label_ids=add_label_ids,
+        remove_label_ids=remove_label_ids,
+    )
+    return {
+        "output": {
+            "status": "updated",
+            "archive": archive,
+            "updated_count": len(ids),
+            "ids": ids,
+            "account_ref": account_ref,
+        }
+    }
+
+
+def _invoke_update_labels(
+    *,
+    input_data: dict[str, Any],
+    access_token: str,
+    account_ref: str,
+) -> dict[str, Any]:
+    ids = _required_string_list(
+        input_data.get("ids"),
+        field_name="ids",
+        max_items=100,
+    )
+    add_label_ids = _required_string_list(
+        input_data.get("add_label_ids"),
+        field_name="add_label_ids",
+        max_items=100,
+        allow_empty=True,
+    )
+    remove_label_ids = _required_string_list(
+        input_data.get("remove_label_ids"),
+        field_name="remove_label_ids",
+        max_items=100,
+        allow_empty=True,
+    )
+    if not add_label_ids and not remove_label_ids:
+        raise BridgeError(
+            "capability_invalid_input",
+            "at least one of add_label_ids or remove_label_ids is required",
+        )
+
+    _gmail_modify_messages(
+        access_token=access_token,
+        ids=ids,
+        add_label_ids=add_label_ids,
+        remove_label_ids=remove_label_ids,
+    )
+    return {
+        "output": {
+            "status": "updated",
+            "updated_count": len(ids),
+            "ids": ids,
+            "add_label_ids": add_label_ids,
+            "remove_label_ids": remove_label_ids,
+            "account_ref": account_ref,
+        }
+    }
+
+
 def _invoke_list_events(
     *,
     input_data: dict[str, Any],

tests/test_bundled_gog_skill.py

@@ -50,3 +50,10 @@ def test_google_skill_includes_summary_and_day_at_a_glance_playbooks() -> None:
     assert "summarize emails" in text
     assert "day at a glance" in text
     assert "get_message" in text
+
+
+def test_google_skill_includes_archive_and_label_mutation_guidance() -> None:
+    text = _load_google_skill_text().lower()
+    assert "archive_messages" in text
+    assert "update_labels" in text
+    assert "always confirm key details" in text

tests/test_gog_capability_e2e.py

@@ -206,6 +206,23 @@ def do_POST(self) -> None:  # noqa: N802
                 )
                 return
 
+            if self.path.startswith(
+                "/gmail/v1/users/me/messages/"
+            ) and self.path.endswith("/modify"):
+                request_body = json.loads(body)
+                self._json_response(
+                    200,
+                    {
+                        "id": self.path.split("/")[-2],
+                        "labelIds": request_body.get("addLabelIds", []),
+                    },
+                )
+                return
+
+            if self.path == "/gmail/v1/users/me/messages/batchModify":
+                self._json_response(204, {})
+                return
+
             # /calendar/v3/calendars/{calendarId}/events
             if "/calendar/v3/calendars/" in self.path and self.path.endswith("/events"):
                 request_body = json.loads(body)
@@ -481,6 +498,47 @@ async def test_gog_capability_rpc_stack_round_trip_and_policy_enforcement(
     assert message_output["thread_id"] == "thread_msg_1"
     assert message_output["body_text"] == "Plain body for msg_1"
 
+    # ---- Invoke email archive_messages ----
+    archive_email = await _rpc(
+        server,
+        request_id=62,
+        method="capability.invoke",
+        params={
+            "context_token": user1_private,
+            "capability": "gog.email",
+            "operation": "archive_messages",
+            "input": {"ids": ["msg_1"], "archive": True},
+        },
+    )
+    assert archive_email.error is None
+    assert isinstance(archive_email.result, dict)
+    archive_output = archive_email.result["output"]
+    assert archive_output["status"] == "updated"
+    assert archive_output["archive"] is True
+    assert archive_output["updated_count"] == 1
+
+    # ---- Invoke email update_labels ----
+    update_labels = await _rpc(
+        server,
+        request_id=63,
+        method="capability.invoke",
+        params={
+            "context_token": user1_private,
+            "capability": "gog.email",
+            "operation": "update_labels",
+            "input": {
+                "ids": ["msg_1"],
+                "add_label_ids": ["IMPORTANT"],
+                "remove_label_ids": ["INBOX"],
+            },
+        },
+    )
+    assert update_labels.error is None
+    assert isinstance(update_labels.result, dict)
+    labels_output = update_labels.result["output"]
+    assert labels_output["status"] == "updated"
+    assert labels_output["updated_count"] == 1
+
     # ---- Auth begin + complete for calendar ----
     begin_calendar = await _rpc(
         server,