[New_Skill] (office/gmail_handler): Gmail IMAP/SMTP skill for agent mail workflows (#208)

[rosspeili]

Summary

Adds office/gmail_handler: deterministic Gmail IMAP/SMTP operations for agent mail workflows (#208).

The host agent owns NLU, drafting, and user confirmation. The skill owns transport, address-book resolution, preview/confirm gates, inbox search/read, sent-folder + local send-ledger lookup, scan cursor, and context carry-forward across turns.

Live-tested: resolve → send → search → read → reply path against a dedicated agent mailbox.

Closes #208

Type of Change

• New Skill — new registry bundle under skills/
• Skill Upgrade — changes to an existing skill under skills/
• Bug Fix — incorrect runtime or framework behavior
• Documentation — docs, README, CONTRIBUTING only
• Framework Feature — skillware/core/ loader, env, adapters
• CLI — skillware/cli.py, docs/usage/cli.md
• Examples — examples/*.py, agent loops, examples/README.md
• Packaging — pyproject.toml optional extra via sync_extras
• RFC / meta — templates, labels, CI, or large design doc

Checklist (all PRs)

• Linked GitHub issue (Refs #208)
• Scope matches the issue — no unrelated refactors
• black / flake8 pass on touched paths
• pytest skills/office/gmail_handler/ and pytest tests/ pass
• CHANGELOG.md updated under [Unreleased]
• examples/README.md updated
• pytest tests/test_registry_docs.py pass

New skill: office/gmail_handler

Bundle and metadata

• skills/office/gmail_handler/ — stdlib-only (no manifest requirements)
• manifest.yaml — actions, env_vars, constitution, issuer
• card.json issuer matches manifest

Logic, cognition, tests

• Deterministic skill.py + mail.py / addressbook.py (no LLM in skill)
• instructions.md — agent vs skill responsibilities, context playbook
• test_skill.py — mocked IMAP/SMTP (22 tests)
• tests/skills/office/test_gmail_handler.py — MIME/threading edge cases
• SkillLoader.load_skill("office/gmail_handler") succeeds

Documentation and catalog

• docs/skills/gmail_handler.md + catalog row
• Runnable: gmail_handler_demo.py, gemini_gmail_handler.py
• agent_loops.md, api_keys.md, .env.example updated
• Full provider matrix (Claude/OpenAI/DeepSeek/Ollama) — catalog snippets only for v1; Gemini has runnable example

Acceptance criteria (#208)

Criterion	Where
Action-based JSON API (no regex DSL)	skill.py, instructions.md
Preview before send/reply	preview_send, preview_reply, confirmed gate
Editable address book	data/addressbook.yaml, update_addressbook, GMAIL_ADDRESSBOOK_PATH
Incremental inbox scan	since_uid, mailbox_status, scan state file
Mocked CI tests	test_skill.py, maintainer tests
Dedicated agent mailbox docs	gmail_handler.md, api_keys.md, constitution
Empty bundled address book	data/addressbook.yaml (template only)

Constitution and safety

• Dedicated agent mailbox — GMAIL_ADDRESS + App Password; not for personal inboxes (documented like agent wallet guidance).
• Confirm before send — send / reply require confirmed: true by default.
• Fail closed — missing creds, ambiguous recipients, recipient cap.
• Untrusted inbound — read_message sets untrusted_content: true.
• No secrets in repo — runtime ledger/scan state gitignored under data/.

Out of scope (follow-up issues)

• CLI skillware mail … + global config mail section
• OAuth / Gmail API
• Attachments
• OAuth v2

Test plan

• pytest skills/office/gmail_handler/test_skill.py tests/skills/office/test_gmail_handler.py tests/test_registry_docs.py
• python examples/gmail_handler_demo.py (mocked)
• Live smoke: resolve → send → search → read (dedicated agent account)