[feat] Add productivity agent with Google Calendar and Gmail integration

[kyegomez]

Summary

Add a ProductivityAgent worker to ClawSwarm that gives the swarm full access to a user's Google Workspace — specifically Google Calendar (read/write) and Gmail (read, reply, follow-up) — so the agent can manage schedules and handle email workflows autonomously.

Motivation

The existing worker agents cover search, development, and token operations. A productivity agent would let the swarm act as a true personal assistant: scheduling meetings, checking availability, drafting and sending replies, and following up on unanswered threads — all from a single conversational interface.

Proposed Capabilities

Google Calendar

• Read — list upcoming events, check availability, find free slots
• Write — create, update, and delete events; add attendees; set reminders
• Smart scheduling — find mutual availability across multiple attendees and propose times

Gmail

• Read — fetch inbox, search threads, summarize email chains
• Reply — draft and send context-aware replies to existing threads
• Follow-up — detect emails awaiting a response and send polite follow-ups after a configurable delay
• Compose — draft new emails from a brief user description

Proposed Implementation

Follow the existing create_*_agent pattern in claw_swarm/agent/worker_agents.py:

# claw_swarm/tools/google_tools.py
def calendar_list_events(time_min: str, time_max: str) -> list[dict]: ...
def calendar_create_event(summary: str, start: str, end: str, attendees: list[str]) -> dict: ...
def gmail_list_threads(query: str, max_results: int) -> list[dict]: ...
def gmail_send_reply(thread_id: str, body: str) -> dict: ...
def gmail_send_new(to: str, subject: str, body: str) -> dict: ...

# claw_swarm/agent/worker_agents.py
def create_productivity_agent(...) -> Agent: ...

Auth is handled via OAuth 2.0 with a locally stored token.json (standard Google API flow).

Acceptance Criteria

• claw_swarm/tools/google_tools.py — Calendar and Gmail tool functions
• create_productivity_agent() factory in worker_agents.py following existing patterns
• PRODUCTIVITY_SYSTEM_PROMPT covering calendar and email workflows
• OAuth 2.0 setup with credentials.json + token.json (standard Google flow)
• Required scopes: calendar, gmail.modify
• Environment / config support: credentials path configurable via env var or config file (see [feat] Add agent config file support for name, description, and custom prompt #14)
• Token refresh handled transparently (no re-auth on every run)
• ProductivityAgent registered in the main agent router / swarm
• Unit tests with mocked Google API responses
• Docs: OAuth setup walkthrough, required scopes, example prompts

Environment Variables

GOOGLE_CREDENTIALS_PATH=~/.claw_swarm/credentials.json
GOOGLE_TOKEN_PATH=~/.claw_swarm/token.json

Example Prompts

"What meetings do I have tomorrow?"
"Schedule a 30-minute call with alice@example.com on Thursday afternoon."
"Summarize my last 5 unread emails."
"Reply to the email from Bob about the Q1 report and say I'll review it by Friday."
"Follow up on any emails I haven't responded to in the last 3 days."

Notes

• Credentials must never be committed to the repo — add credentials.json and token.json to .gitignore
• Follow-up logic should be opt-in and have a configurable delay (default: 3 days)
• All write operations (send, create event, delete) should confirm intent before executing unless the user explicitly enables auto-mode
• Integrates with the upcoming config file ([feat] Add agent config file support for name, description, and custom prompt #14) for credentials path and default behavior settings