/google-loops

name: google-loops
version: 1.0.0
description: |
  Set up and operate the Gmail/Calendar/Contacts connector and the open-loop
  engine: who is waiting on the user, what they promised, and the context
  needed to respond. Covers painless BYO OAuth setup (exactly two user
  interactions), the daily `gbrain waiting` digest, loop closing/muting, and
  troubleshooting via the typed error catalog.
triggers:
  - "connect gmail"
  - "connect google"
  - "connect calendar"
  - "connect contacts"
  - "who is waiting on me"
  - "what do I owe people"
  - "open loops"
  - "unanswered email"
  - "set up email ingestion"
  - "gbrain waiting"
tools:
  - open_loops
  - loops_close
  - loops_mute
  - entity
  - context_pack
mutating: true
writes_pages: false

Google Loops — Setup and Daily Operation

The connector ingests Gmail threads, calendar events, and contacts into the brain and maintains the open-loop record behind `gbrain waiting`. Full references: `docs/guides/google-connect.md` (setup + every error and its fix) and `docs/guides/open-loops.md` (how detection works).

Contract for the harness (read first)

1. **Relay `[SHOW USER]` blocks verbatim.** Setup commands print fenced `[SHOW USER] ... [/SHOW USER]` blocks — numbered steps with deep links. Pass them to the user unchanged (paraphrasing loses load-bearing detail like "Desktop app, NOT Web application"). Batch everything into ONE message per block. 2. **The whole setup is exactly two user interactions.** (1) The Google Cloud checklist + the user hands back the downloaded client JSON. (2) The user clicks one consent URL. If you find yourself asking a third question, re-read the block you skipped. 3. **Never put secrets in argv or chat when avoidable.** When the user drops `client_secret_*.json` into chat, save it to a file (mode 0600) and pass the path: `gbrain google connect --client-json <path>`. Env (`GOOGLE_CLIENT_ID`/`GOOGLE_CLIENT_SECRET`) also works. Raw `--client-id/--client-secret` flags are the last resort. 4. **Every command speaks JSON.** Add `--json` and read `{ ok, status, next_action: { command, user_message }, error }`. When `next_action.user_message` is present, that IS the message to show the user; when `next_action.command` is present, that is your next call. Errors carry `{ code, problem, cause, fix, doc_url }` — show the user `problem` + `fix`, nothing else. 5. **Re-running is always safe.** `gbrain google connect` and `gbrain google setup` are idempotent state machines — the documented fix for most errors is "run it again."

Setup (the one command)

gbrain google setup --json

Handles: credential intake (prints the GCP checklist when nothing is on file) → consent (loopback locally; auto paste-back over SSH/headless — non-TTY flows complete via a second call: `gbrain google connect --code "<pasted-redirect-url>"`) → source registration → a budgeted first sync (newest mail first; the deep backfill resumes on later syncs automatically) → the first `gbrain waiting` digest.

Multiple accounts: repeat with `--account work@example.com`.

Already holding Google access another way (a Google CLI with its own auth, `gcloud`, a credential gateway that mints tokens)? Skip OAuth and point the source at it — no credential enters gbrain:

gbrain sources add gmail-work --kind google --account you@example.com \
  --access command --token-command "<command that prints an access token>"

(`--access env --token-env <VAR>` reads an externally-refreshed token from the environment instead.) Then `gbrain sync --source gmail-work` and `gbrain waiting` work identically.

Verify health afterwards: `gbrain google status --json` (per-account refresh probe) — and `gbrain doctor` carries a `google_oauth` check that warns once a Testing-mode account goes 5+ days without a successful refresh. An actively-syncing account gets no pre-warning before the 7-day Testing-mode expiry — publishing to Production is the real fix.

Daily operation

gbrain waiting --json        # the killer output: ranked people waiting
gbrain loops done <id>       # user handled it
gbrain loops drop <id>       # user is not going to do it
gbrain loops mute sender <email>   # never track this sender again (closes its open reply-owed loops)
gbrain loops unmute sender <email> # undo; the loops it closed are re-checked on the next sync
gbrain loops drop sender <email> --dry-run   # preview closing one sender's reply-owed loops

• `waiting` may end with `withheld_noise`: open reply-owed loops from senders

whose mail is automated (bank or shipping alerts). Show the user each `preview_command`, run it (`--dry-run` changes nothing), and drop only after the user agrees: a drop cannot be undone. Offer `loops mute sender` when the user wants a stop they can reverse.

• `waiting` REFUSES on stale data (no successful sync in 24h) and names the

exact fix (`gbrain sync --source <id>`). Run the sync, then retry. Only use `--stale-ok` when the user explicitly accepts stale results.

• `completeness: "partial"` means some mail in the last 14 days is held after

repeated import failures (listed in `held`), or, with `no_google_sources: null`, the sources could not be read (retry). Present the answer as partial: name each held item (sender, and subject when shown) and its retry command (`gbrain sources retry-held <id>`). Never say "you are clean" on a partial answer.

• When presenting loops, show: the counterparty, what's owed (summary), the

evidence quote, the deep link (opens the exact Gmail thread in the right account), and the due date when present. The trusted-local result already carries a paste-ready `text` digest — reuse it.

• For "context to respond": each group carries the counterparty's entity

card (summary, recent history, other open threads). Need more, call `context_pack` with the counterparty slug.

• After the user says they replied/handled something,