Google Loops

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

• 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). 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, close the loop (loops done) — thread loops also self-close on the next sync when the reply is visible in Gmail.

Continuous ingestion

Google sources sync like any source: autopilot and gbrain sync --all pick them up automatically. No cron of its own. A bare un-targeted gbrain sync does NOT reach them — use --source <id> or --all.