feat: add Google Workspace / Microsoft 365 API integration

[avoidwork]

Summary

Add tools for interacting with Google Workspace (Docs, Sheets, Drive) and Microsoft 365 (Word, Excel, OneDrive) via their respective APIs.

Motivation

The existing file extraction tools only handle local files. Real office workflows live in cloud productivity suites — Google Docs, Google Sheets, Google Drive, Microsoft Word, Microsoft Excel, OneDrive. Users need to create, edit, and manage documents in these platforms directly. Currently the agent can only work with local files via shell commands, which is fragile and disconnected from where the work actually happens.

Proposed Solution

Create API integration tools for:

• Google Docs: Create, read, update, comment on documents via Google Docs API
• Google Sheets: Read/write data, run formulas, manage sheets via Google Sheets API
• Google Drive: File management, sharing, permissions via Google Drive API
• Microsoft Word: Create, edit, format documents via Microsoft Graph API
• Microsoft Excel: Read/write cells, formulas, formatting via Microsoft Graph API
• Microsoft OneDrive: File sync, sharing, permissions via Microsoft Graph API

Each tool should follow the existing tool pattern in src/tools/ — a zod schema, an impl function, and registration in index.js with appropriate permissions.

Alternatives Considered

• Shell-based tools (gcloud, az cli): fragile, requires user-installed dependencies, no real-time sync.
• Read-only local file extraction: insufficient for collaborative workflows.
• Browser automation: adds infrastructure complexity, slower than API calls.

OpenSpec Note

This project uses OpenSpec for feature development. If this request is approved, I will:

1. Run /opsx:propose to generate a full proposal with specs and tasks
2. Iterate on the design before any code is written
3. Follow the task-driven implementation workflow

Additional Context

This should integrate with the document creation gap (#778) and calendar management gap (#781) — e.g., creating a Google Doc and then scheduling a meeting about it. The existing fileExtract tools (docx.js, xlsx.js) would serve as the local file counterpart to these cloud tools.

Dependencies

• Google Workspace: googleapis (v144.x) — official Google API client for Node.js. Supports Docs, Sheets, Drive APIs. Requires OAuth 2.0 or service account credentials.
• Microsoft 365: @microsoft/microsoft-graph-client (v3.x) — official Microsoft Graph API client. Supports Word, Excel, OneDrive APIs. Requires OAuth 2.0 or Azure AD app registration.
• OAuth flow: google-auth-library (v9.x) for Google OAuth. @azure/identity (v4.x) for Microsoft OAuth. Both support device flow for headless environments.
• Credential storage: SQLite via better-sqlite3 (v11.x) for storing OAuth tokens securely. Tokens are encrypted at rest using a master key from process.env.

Testing Strategy

• Unit tests: Mock OAuth token refresh, API response parsing, and Zod schema validation. Verify error handling for common API errors (401, 403, 429, 500).
• Integration test: Use Google's and Microsoft's test/sandbox environments. Google has a sandbox environment for Drive API testing. Microsoft has a test tenant for Graph API.
• OAuth flow: Test the device flow for headless authentication. Verify token storage and refresh.
• Edge cases: Large documents (>10MB), missing files, permission denied, API rate limits, network timeouts, concurrent edits.

Security Considerations

• OAuth tokens: Stored encrypted in SQLite using a master key from process.env. Tokens are never logged, returned in API responses, or stored in plain text.
• API key/credential storage: All credentials (Google client secret, Microsoft client secret, refresh tokens) stored in process.env or encrypted SQLite only — never in config files or logs.
• Permission scopes: Use the principle of least privilege. Request only the scopes needed for each operation (e.g., "read-only" for reading documents, "read-write" for editing).
• Rate limiting: Both Google and Microsoft enforce strict rate limits. Implement client-side rate limiting (default: 10 requests/second per API) with automatic retry on 429 responses (exponential backoff).
• URL allowlist: All outbound API requests must validate against an allowlist per AGENTS.md 1.2. Disallow file://, gopher://, dict:// schemes.
• PII handling: Document content may contain sensitive data. Strip PII before logging (per AGENTS.md 1.2). Do not store document content in logs or error messages.
• File sharing: When sharing files via Drive/OneDrive, default to "link with password" or "specific people" — never "anyone with the link" unless explicitly requested.
• Token refresh: Implement automatic token refresh before expiration. If refresh fails, return a clear error to the user prompting re-authentication.

Implementation Notes

• Split into three tools:

  1. google-docs (create, read, update, comment)
  2. google-sheets (read, write, formulas, manage sheets)
  3. google-drive (file management, sharing, permissions)
  4. microsoft-word (create, edit, format)
  5. microsoft-excel (read, write, formulas, formatting)
  6. microsoft-onedrive (file sync, sharing, permissions)

  Start with google-docs and google-sheets as the MVP (most common use case). Defer Microsoft tools and Google Drive to follow-up PRs.

• Zod schema for google-docs: { action: "create" | "read" | "update" | "comment" | "list", documentId?: string, title?: string, content?: string, commentText?: string, parentId?: string }.

• Zod schema for google-sheets: { action: "read" | "write" | "append" | "run-formula" | "list", spreadsheetId?: string, range?: string, values?: unknown[], formula?: string }.

• OAuth setup: On first use, the tool checks for valid tokens. If none exist, it returns an auth URL for the user to complete the OAuth flow (device code). Tokens are stored encrypted and reused for subsequent calls.

• Error handling: Return structured error objects with API error code, message, and retry suggestion. Never expose raw API error responses to the agent.

• Caching: Cache read operations (document content, sheet data) with TTL (default: 5 minutes). Invalidate cache on write operations.

• Batch operations: Support batch operations where the API allows (e.g., batch read multiple sheets, batch update multiple cells). This reduces API calls and improves performance.

• Local file sync: Consider adding a sync feature that downloads Google Docs/Sheets to local files and vice versa. This can be a follow-up PR after the core API tools are implemented.

• CI considerations: Google and Microsoft test environments require separate setup. Skip integration tests in CI unless test credentials are available. Use mock responses for unit tests.