AlexandrAI AGENTS.md
agents-md

Personal Work Agent Google Calendar Connector Agent Guide

Project-specific AGENTS.md guidance for the Personal Work Agent Google Calendar connector boundary, platform files, tests, cursor or client behavior, ingestion, validation, and redaction rules.

AGENTS.md

Guidance for coding agents working on the Personal Work Agent Google Calendar connector boundary.

Project Overview

The Google Calendar connector boundary keeps platform-specific API access, cursor sync, event normalization, and case creation separate from the generic runtime. Use this guide when changing Google Calendar request shapes, sync cursors, watch-profile scoping, ingest mapping, validation behavior, or connector-specific tests.

This document is intentionally narrower than the broad connector guide. It is for agents already touching Google Calendar-specific files.

Project Map

  • src/workagent/connectors/google_calendar_client.py
  • src/workagent/connectors/google_calendar_sync.py
  • src/workagent/services/google_calendar_ingest.py

Relevant tests:

  • tests/test_google_calendar_adapter.py
  • tests/test_google_calendar_sync.py
  • tests/test_google_calendar_ingest.py

Setup Commands

bashuv run pytest tests/test_google_calendar_adapter.py tests/test_google_calendar_sync.py tests/test_google_calendar_ingest.py -q
uv run pytest tests/test_connector_validation.py tests/test_platform_event_normalization.py -q
make lint

Connector Notes

  • Calendar sync is time-window sensitive.
  • Keep event IDs, updated timestamps, and calendar scope stable.

Change Rules For Agents

  • Keep raw platform API calls in connector client files.
  • Keep pagination, cursor parsing, and batch construction in connector sync files when a sync file exists.
  • Keep platform event to local case conversion in the matching ingest service when an ingest service exists.
  • Use credentials through the configured credential resolver and secret store; do not pass raw token values into cases.
  • Preserve watch-profile and query scoping before broad collection.
  • Normalize remote IDs consistently so duplicate events do not create duplicate local cases.
  • Keep platform-specific errors typed and covered by focused tests.

Verification

bashuv run pytest tests/test_google_calendar_adapter.py tests/test_google_calendar_sync.py tests/test_google_calendar_ingest.py -q
make lint

Run runtime factory tests too if connector registration changes.

Security Notes

Google Calendar data can include private workspace content, user identifiers, files, tickets, messages, and credentials. Do not publish tokens, private endpoints, tenant identifiers, message bodies, file links, or account-specific IDs. Use placeholders in examples.

PR Checklist

  • Client behavior is covered by platform tests.
  • Cursor and duplicate handling are covered when sync exists.
  • Ingest conversion is covered when ingest exists.
  • Credential handling stays resolver-owned and redacted.