Google OAuth

Files (1)

• SKILL.md

SKILL.md (first lines)

# Google OAuth

Drives the agent's access to the user's Google services — Gmail,
Drive, Calendar, Sheets, Photos, YouTube Data, Tasks, and every other
`*.googleapis.com` endpoint. Backed by 4 tools (`google_auth_start`,
`google_auth_status`, `google_call`, `google_auth_revoke`) that wrap a
real OAuth 2.0 installed-application flow with a loopback callback and
persistent refresh tokens.

## Use when

- "Read my last 10 Gmail emails"
- "Create a Calendar event for tomorrow at 3pm"
- "Find the 'Q4 budget' document in my Drive"
- "Add a row to my expenses Sheet"
- "Delete the videos I uploaded to YouTube this month"

## Do not use when

- **Google apps that do not belong to this user** (an admin's Drive,
  someone else's Gmail) — each agent can only access the account that
  granted consent.
- **Free actions that do not require account auth** (public search,
  no-account maps, etc.) — use dedicated tools (`ext_wikipedia_search`,
  etc.) that do not consume Google API quota.
- **Gemini / AI Studio** — that path does not use OAuth; it uses
  direct API-key auth (`GEMINI_API_KEY`).

## Canonical workflow

First turn where the user asks for a Google action:

```
1. google_auth_status()
   → { authenticated: false, reason: "no tokens on file" }

2. google_auth_start()
   → { ok: true, url: "https://accounts.google.com/o/oauth2/v2/auth?...",
       redirect_uri: "http://127.0.0.1:8765/callback",
       instructions: "Open this URL..." }

3. Send this to the user in chat:
   "To let me read your Gmail, open this link and approve permissions:
    <url>. If you're connected through a remote server, use an SSH
    tunnel: `ssh -L 8765:127.0.0.1:8765 <host>`. Tell me when you're done."

4. Wait for the user's next message. DO NOT retry tools meanwhile.

5. When the user replies "done" (or similar):
   google_auth_status()
   → { authenticated: true, expires_in_secs: 3589, has_refresh: true,
       scopes: [...] }

6. Now run `google_call(...)` for the user's requested task.
```

All following calls (including future sessions days later) only need
direct **`google_call`**. The persisted refresh token automatically
renews access tokens — the user does not see consent again unless they
revoke access.

## Tool reference

| Tool | When to call |
|---|---|
| `google_auth_status` | Before the first Google operation in each session. Fast diagnostic — no network calls. |
| `google_auth_start` | Only if `status.authenticated == false`. Requires human action (click + browser consent). No retries/polling by the LLM — wait for the next user message. |
| `google_call` | The workhorse. 99% of your calls. |
| `google_auth_revoke` | Only if the user explicitly asks to disconnect Google. Invalidates the token in Google. |

## `google_call` — API examples

### Gmail

```json
{ "method": "GET",
  "url": "https://gmail.googleapis.com/gmail/v1/users/me/messages?maxResults=10" }

{ "method": "GET",
  "url": "https://gmail.googleapis.com/gmail/v1/users/me/messages/{id}?format=full" }

{ "method": "POST",
  "url": "https://gmail.googleapis.com/gmail/v1/users/me/messages/send",
  "body": { "raw": "<base64-encoded RFC 2822 message>" } }
```

Required scope: `gmail.readonly` (read) or `gmail.modify` (send/trash).

### Calendar

```json
{ "method": "GET",
  "url": "https://www.googleapis.com/calendar/v3/calendars/primary/events?timeMin=2026-04-24T00:00:00Z" }

{ "method": "POST",
  "url": "https://www.googleapis.com/calendar/v3/calendars/primary/events",
  "body": {
    "summary": "Dentist",
    "start": {"dateTime": "2026-04-25T15:00:00-05:00"},
    "end":   {"dateTime": "2026-04-25T16:00:00-05:00"}
  } }
```

Scope: `calendar.readonly` or `calendar.events`.

### Drive

```json
{ "method": "GET",
  "url": "https://www.googleapis.com/drive/v3/files?pageSize=50&q=name contains 'budget'" }

{ "method": "GET",
  "url": "https://www.googleapis.com/drive/v3/files/{fileId}?fields=*" }
```

Scope: `drive.readonly` or `drive`.

### Sheets

From lordmacu/nexo-rs, Apache-2.0.

More from lordmacu/nexo-rs