Google Workspace Plugin

Lets the assistant work in the signed-in user's Gmail, Calendar, Docs, Sheets, and Drive — search and read by default, and (after approval) send mail, manage events, and edit documents. Each user connects their own Google account; there is no shared instance credential.

It sits on top of the OAuth plugin, which stores tokens and runs the Google consent flow. Users connect from Settings → Extensions → Google Workspace; they never have to visit a separate "OAuth" screen.

Using it

Connect your Google account

Open Settings (gear icon) → Extensions → Google Workspace.
Choose which products to grant, and at which level:

| Product | Read only | Broader grant |
|---------|-----------|----------------|
| Gmail | Search and read mail | Read & send — also send, draft, label, and trash (not permanent deletion) |
| Calendar | List calendars and read events | Manage events — also create, update, and delete events |
| Docs | Read document text | Read & edit — also create documents and edit text |
| Sheets | Read spreadsheet values | Read & edit — also create spreadsheets and edit values |
| Drive (file search) | Find Docs and Sheets by name or full text | (search only) |

Click Connect. Google's consent screen opens in the browser. After you approve, Codumentor stores the grant for your user.
You can later narrow or broaden those choices in the same settings section, or disconnect the account.

The assistant only receives tools that match the products and levels you granted. If you connect Gmail as read-only, it cannot send mail until you raise that level and reconnect.

The TUI has the same picker under Settings → Google Workspace.

Talk to the assistant

Once connected, ask in ordinary language, for example:

"What unread mail did I get from Alice this week?"
"Put a 30-minute review on my calendar tomorrow at 10."
"Find the Q2 planning Doc and summarise the risks section."
"Add a row to the expenses Sheet for today's lunch."

Read tools run without a prompt. Anything that sends mail, changes a calendar, or edits a Doc/Sheet asks for approval first (Allow once / Allow for this conversation / Create a rule / Deny), the same way a shell command does.

If you are not connected, or a needed product is missing, the tool returns a message pointing you back to Settings → Google Workspace — it does not call Google.

What the assistant can do

Gmail

Tool	Approval	Purpose
`gmail_search`	none	Search or list messages (Gmail search syntax, e.g. `from:alice is:unread`)
`gmail_get_message`	none	Read one message (headers, body, attachment list)
`gmail_get_thread`	none	Read a whole conversation
`gmail_list_drafts`	none	List saved drafts
`gmail_list_labels`	none	List labels / folders
`gmail_get_attachment`	none	Download one attachment into the staging area so it can be copied into a repo — the bytes do not enter the chat
`gmail_send`	`gmail.send`	Send a new message, or send an existing draft
`gmail_draft`	`gmail.draft`	Create or update a draft
`gmail_delete_draft`	`gmail.draft`	Discard a draft
`gmail_modify_message`	`gmail.modify`	Add/remove labels (read/unread, archive, star, move)
`gmail_trash_message`	`gmail.trash`	Move a message to Trash, or restore it
`gmail_manage_label`	`gmail.label`	Create, rename, or delete a label

Permanent Gmail deletion is not exposed.

Calendar

Tool	Approval	Purpose
`calendar_list_calendars`	none	List calendars the account can see
`calendar_list_events`	none	List events in a time window
`calendar_get_event`	none	Read one event in full
`calendar_create_event`	`calendar.event.create`	Create an event
`calendar_update_event`	`calendar.event.update`	Update an event
`calendar_delete_event`	`calendar.event.delete`	Delete an event

Drive, Docs, Sheets

Tool	Approval	Purpose
`drive_search`	none	Find Docs/Sheets (and other files) by name or full text
`docs_get_document`	none	Read a Doc as compact text
`docs_create_document`	`docs.create`	Create a Doc
`docs_replace_text`	`docs.edit`	Replace exact text matches
`docs_insert_text`	`docs.edit`	Insert text at an anchor
`sheets_get_spreadsheet`	none	Spreadsheet overview (tabs)
`sheets_read_values`	none	Read an A1 range
`sheets_create_spreadsheet`	`sheets.create`	Create a spreadsheet
`sheets_update_values`	`sheets.edit`	Write an A1 range
`sheets_append_values`	`sheets.edit`	Append rows
`sheets_clear_values`	`sheets.edit`	Clear an A1 range

drive_search is how the assistant finds a Doc or Sheet; the Docs/Sheets tools then open it by id. Drive access is read-only — the plugin does not upload, move, or share Drive files.

Who gets which half

Two gates, not one. target_agents (default main) decides whether the family is offered at all; write_target_agents (default main) then decides who gets the tools in the "Approval" column above.

The family default stays closed because these tools act on a real mailbox and calendar, and nobody reads a subagent's tool calls before they land. The second gate is what makes opening it a decision about reading: with target_agents: all, a research subagent can search mail and list events, and still cannot send, edit, trash, or delete anything. Set write_target_agents: all only if subagents should write too.

Configuration

Load both the OAuth plugin and this plugin. This plugin's priority must be lower than OAuth's (3 vs 4) so Google is available when OAuth starts serving connect flows.

plugins:
  - module: codumentor.plugins.oauth
    class: OAuthPlugin
    priority: 4
    args:
      enabled: true

  - module: codumentor.plugins.google_workspace
    class: GoogleWorkspacePlugin
    priority: 3
    args:
      enabled: true
      client_id: ${GOOGLE_OAUTH_CLIENT_ID}
      client_secret: ${GOOGLE_OAUTH_CLIENT_SECRET}

Connecting an account requires the oauth:manage permission, which the built-in power_user and admin roles have. Grant it to other roles if ordinary users should connect Google themselves.

Also set auth.jwt_secret so tokens are encrypted at rest (see OAuth). For a deployment that is not on localhost, set api.external_url so Google can redirect back after consent.

Google Cloud project

In Google Cloud Console, create or pick a project.
Enable the APIs the tools need: Gmail, Google Calendar, Google Docs, Google Sheets, Google Drive.
Configure the OAuth consent screen (Internal for a Workspace org, or External with test users while developing).
Create an OAuth 2.0 Client ID of type Web application.
Add an authorized redirect URI: - Internet-facing: {api.external_url}/oauth/callback/google (example: https://codumentor.example.com/oauth/callback/google) - Local: http://127.0.0.1:<port>/oauth/callback/google (<port> is api.port, default 2638)
Copy the client id and secret into GOOGLE_OAUTH_CLIENT_ID / GOOGLE_OAUTH_CLIENT_SECRET (or into the plugin args).

If client_id / client_secret are missing, the plugin loads but does not register Google — tools will tell the user the provider is not configured, and the process does not crash.

Parameters

Parameter	Type	Default	Description
`enabled`	bool	`true`	Master on/off.
`client_id`	string	`$GOOGLE_OAUTH_CLIENT_ID`	OAuth client id.
`client_secret`	string	`$GOOGLE_OAUTH_CLIENT_SECRET`	OAuth client secret.
`default_scopes`	list	Gmail/Calendar/Docs/Sheets read-write + Drive read + `openid`/`email`	Scopes requested when the user clicks Connect without changing the picker. The picker still offers every product/level.
`filter_tools_by_scope`	bool	`true`	Only offer tools whose scopes the connected account actually grants.
`revoke_on_narrow`	bool	`true`	When the user drops a product or level, revoke the Google grant and re-consent so the removed access is gone upstream, not only locally.
`target_agents`	string	`main`	Who gets the tools: `main`, `subagent`, `all`, or a subagent role name. Default keeps this family off subagents entirely.
`write_target_agents`	string	`main`	Same values, applied to the editing tools only — so widening `target_agents` grants reads without also granting `gmail_send`.
`authorize_url` / `token_url` / `userinfo_url` / `revocation_url`	string	Google's public endpoints	Override only to point at a private Google-compatible IdP.

Read-only default grant

To have Connect request read access unless the user raises a product in the picker:

      default_scopes:
        - openid
        - email
        - https://www.googleapis.com/auth/gmail.readonly
        - https://www.googleapis.com/auth/calendar.readonly
        - https://www.googleapis.com/auth/documents.readonly
        - https://www.googleapis.com/auth/spreadsheets.readonly
        - https://www.googleapis.com/auth/drive.readonly

Notes

Each user authenticates as themselves. Two people in the same Codumentor instance never share a Google token.
Attachment downloads are saved under the instance attachment staging area so the agent can copy them into a repo; size is capped by agent.attachment_staging.max_file_bytes.
Narrowing access re-opens Google's consent screen (needed so a refresh token is re-issued for the smaller grant).
See OAuth for api.external_url, auth.jwt_secret, and the callback URL.