feat(google-workspace): add gmail attachment list/get CLI verbs (#22872)

[briandevans]

Summary

The bundled productivity/google-workspace skill ships a CLI wrapper for
Gmail (search, get, send, reply, labels, modify) but exposes no
surface for downloading attachments. When the agent surfaces emails matching
the SKILL.md example has:attachment filename:pdf newer_than:7d, it then
has no skill-supported way to fetch them — it falls back to ad-hoc Python
or asks the user to download manually.

This adds two subcommands under gmail attachment.

The gap

skills/productivity/google-workspace/scripts/google_api.py has full
plumbing for users.messages.get, send, reply, labels, modify —
but never wires users.messages.attachments.get. The Gmail message
payload references attachments by body.attachmentId, which is opaque
without a second API call to resolve to bytes.

The fix

Two new subcommands following the existing _run_gws / build_service
dual-path pattern:

$GAPI gmail attachment list MESSAGE_ID
# → [{"attachment_id": "...", "filename": "...", "mime_type": "...", "size_bytes": N, "part_id": "..."}]

$GAPI gmail attachment get MESSAGE_ID ATTACHMENT_ID --output /tmp/file.pdf
# → {"status": "saved", "path": "/tmp/file.pdf", "size_bytes": N}

• gmail attachment list walks the message payload via a new
  _walk_attachments() helper that handles nested multipart/* parts
  (cover letter + signed/encrypted wrappers).
• gmail attachment get base64url-decodes the payload and writes bytes
  to disk, creating parent directories as needed.
• Both go through _run_gws when the gws binary is available and fall
  back to googleapiclient otherwise, matching every other verb in the
  file.
• No new OAuth scopes — gmail.readonly already covers
  attachments.get.

Test plan

• Focused: tests/skills/test_google_workspace_api.py — 5 new tests
  (12 total, all pass):
  • _walk_attachments finds attachments across nested multipart
  • _walk_attachments returns empty for text-only payloads
  • gmail attachment list issues the expected messages.get call and
    emits the JSON shape
  • gmail attachment get decodes base64url and writes the raw bytes
    to the output path, creating parent directories
  • gmail attachment get surfaces a clear stderr error and exits 1
    when the API response omits data
• Adjacent suite: tests/skills/ (164 passed) — no regressions in
  bridge / OAuth / sibling skills tests.

Related

• Fixes productivity/google-workspace: CLI wrapper missing attachment download #22872
• Same skill area as previously salvaged PR fix(google-workspace): restore required_credential_files in SKILL.md #19886 (fix(google-workspace): restore required_credential_files in SKILL.md (#16452) #16470 → fix(google-workspace): restore required_credential_files in SKILL.md #19886);
  no overlap with that diff.

[Copilot]

Pull request overview

This PR extends the bundled productivity/google-workspace skill’s Gmail CLI wrapper to support discovering and downloading Gmail attachments, closing the gap where the agent could find attachment-bearing emails but had no skill-supported way to fetch the bytes.

Changes:

• Add gmail attachment list MESSAGE_ID to enumerate attachments from a message payload (including nested multipart structures).
• Add gmail attachment get MESSAGE_ID ATTACHMENT_ID --output PATH to fetch attachment bytes and write them to disk.
• Add/extend tests and update SKILL.md usage examples for the new attachment commands.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
skills/productivity/google-workspace/scripts/google_api.py	Adds _walk_attachments() plus gmail attachment list/get subcommands and wires them into argparse.
tests/skills/test_google_workspace_api.py	Adds tests for attachment walking, listing, downloading, and an error path.
skills/productivity/google-workspace/SKILL.md	Documents the new gmail attachment commands in the Gmail usage section.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[briandevans]

Housekeeping: closing to keep my open-PR set focused on actively-reviewed work. This has been open ~21d without maintainer review and the surrounding code has continued to move, so it's unlikely to land as-is. The underlying fix still stands — happy to reopen and rebase if it would be useful. Thanks!