Skip to content

feat: Gmail API proxy tool and skill #85

@QueryPlanner

Description

@QueryPlanner

What

Add a single gmail_api ADK proxy tool that gates the entire Gmail REST API surface, paired with a Skill that teaches the agent how to use it. Creates tools.db SQLite file in a Docker volume with a gmail_tokens table for OAuth credential storage.

Why

  • Agent needs full Gmail API access, not just a subset of endpoints
  • OAuth tokens must be stored securely server-side (never exposed to sandbox)
  • Token refresh must be transparent (powered by google-auth library)
  • Starts the SQLite infrastructure that Issue Improve Telegram UX with typing, startup logs, and reset #2 will extend with migrated PostgreSQL tables

How

  • Create src/blacki/storage/sqlite.py — SQLite connection manager, opens tools.db, creates gmail_tokens table
  • Create src/blacki/gmail/auth.py — OAuth 2.0 flow, stores/refreshes token JSON in gmail_tokens
  • Create src/blacki/gmail/client.pygmail_api(method, path, params, body) proxy function
  • Create src/blacki/gmail/tools.py — ADK tool wrapping gmail_api()
  • Create src/blacki/gmail/__init__.py — public exports
  • Create src/blacki/skills/gmail/SKILL.md — teaches agent Gmail API query syntax, filters, labels, message ops
  • Create src/blacki/skills/gmail/references/api-reference.md — endpoint quick reference
  • Add CLI: uv run python -m blacki.gmail auth — one-time browser OAuth flow
  • Update pyproject.toml — add google-api-python-client, google-auth-oauthlib, aiosqlite
  • Update src/blacki/registry.py — add gmail_enabled field to ToolConfig, _build_gmail_tools()
  • Update .env.example — add GMAIL_ENABLED, GMAIL_CREDENTIALS_PATH, SQLITE_PATH
  • Update docker-compose.yml — add /data volume mount for tools.db

Sources

Passing Criteria

  • uv run mypy . passes with no new errors
  • uv run ruff check passes
  • uv run ruff format passes
  • uv run pytest --cov=src passes with 100% coverage for new modules
  • uv run python -m blacki.gmail auth completes OAuth flow and stores token in tools.db
  • gmail_api tool appears in agent tool list when GMAIL_ENABLED=true
  • gmail_api handles token refresh transparently (test with expired token mock)
  • tests/gmail/ covers auth flow, client proxy, and tool registration

Priority: High
Level of Effort: Large (6-8 hours)

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions