From b26c0edf235b9e77554c3f3053738f4e5d9bc5fe Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Wed, 18 Nov 2026 09:37:40 -0600 Subject: [PATCH] docs(connections): record the staging Google tester state and findings (#22179) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The built-in Google Workspace connector is going through Google approval > - `doc/memory/google-connector-memory.md` holds the decisions and environment state for that work > - The staging tester now exists and passed its first live tests, but the doc still says "to be created" > - This pull request records the tester state, the remaining wiring order, and the test findings > - The benefit is that the next session starts from the true state and does not break staging deploys ## Linked Issues or Issue Description Docs are out of date. The working memory and the production checklist say the staging tester does not exist. Refs #22050, #22065. ## What Changed - `doc/memory/google-connector-memory.md`: tester state, what passed, what is left, and four findings from live tests. - `doc/plans/2026-11-17-google-workspace-production-checklist.md`: split the tester item into "created" (done) and "wired to the new Google app" (open). ## Verification - Docs only. No code or tests changed. - Checked that the diff has no client ids, project ids, stack ids, passwords, or keys. ## Risks - Low. Docs only. The doc is temporary and is deleted when the connector is released. ## Model Used - Anthropic Claude Fable 5.2 (`claude-fable-5-2`), in Claude Code with tool use and browser control. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Fable 5.2 --- doc/memory/google-connector-memory.md | 81 ++++++++++++------- ...7-google-workspace-production-checklist.md | 4 +- 2 files changed, 54 insertions(+), 31 deletions(-) diff --git a/doc/memory/google-connector-memory.md b/doc/memory/google-connector-memory.md index 6d03b4932fd..e7f62d64638 100644 --- a/doc/memory/google-connector-memory.md +++ b/doc/memory/google-connector-memory.md @@ -12,7 +12,7 @@ Related: [production checklist](../plans/2026-11-17-google-workspace-production- [code-fix plan](../plans/2026-11-17-google-workspace-code-fixes.md), [connector doc](../connections/GOOGLE-WORKSPACE.md). -Last updated: November 17, 2026 (night). +Last updated: November 18, 2026. ## Decisions @@ -98,13 +98,12 @@ From the folder README (`server/src/google-workspace-rest-tools/README.md`). to REST. - **What we send to the reviewers.** Not decided: the new staging tester or something else. Whatever it is must use the separate Google app (below). -- **How the staging tester reaches the separate Google app.** The broker - cannot point one workspace at a different Google client (see - "Environments"). Recommendation: add a per-workspace client override to the - broker so reviewers see the real flow. -- **Reviewer login on staging.** The scoped reviewer password login is - hard-coded to the production tester. The client override above does not fix - this; how to enable the login on staging is still undecided. +- **Staging tester on the separate Google app.** The broker now has a + per-workspace client override; it is not switched on for the tester yet. + The remaining steps and their order are in "Environments". +- **Reviewer login on staging.** The broker now allows the scoped reviewer + password login on the staging tester host. Its secret is not set yet; no + broker change is needed. - **AI-agent client and REST.** Whether an OAuth client marked for AI agents may call the REST APIs rather than MCP. To check before the staging tester is wired. @@ -127,12 +126,11 @@ From the folder README (`server/src/google-workspace-rest-tools/README.md`). ## Next steps -1. Cloud broker changes: limit the unified profile to the 14; cap extra - reported scopes instead of failing; stop offering Chat, People and Search - on the verified client; turn on revoke support; add a per-workspace Google - client override. -2. Create the staging tester (`googletester.staging.paperclip.app`). -3. Live acceptance on the staging tester. +1. Deploy the Cloud broker changes to production. They are merged and live + on staging (see "Cloud broker"); the production deploy is manual and + waits for Dotta. +2. Point the staging tester at the separate Google app (see "Environments"). +3. Finish live acceptance on the staging tester. 4. Switch services to REST one at a time, each after its live test. 5. Revoke at Google when the last connection is removed. 6. Security scans. @@ -143,23 +141,43 @@ From the folder README (`server/src/google-workspace-rest-tools/README.md`). | Name | Address | Notes | | --- | --- | --- | | Earlier tester | `googletester.paperclip.app` (company prefix `GOO`) | On **production**. Used for earlier tests. Hard to deploy to; do not build on it further. | -| New tester | `googletester.staging.paperclip.app` | **To be created** on staging. Engineering qualification happens here. | +| New tester | `googletester.staging.paperclip.app` (company prefix `GOO`) | **Created November 18** on staging. Engineering qualification happens here. State below. | | Test 02 | In the private handoff | Staging stack used for the October proof. Holds Dotta's own Gmail grant, so not for reviewers. | | Reviewer destination | Undecided | See "Still open". | -Creating the staging tester (as reported by the Nov 17 read-only audit; not yet -done): +Staging tester state (November 18): -1. On the staging account site, create an organization with the slug - `googletester`. That gives `googletester.staging.paperclip.app`. -2. Pin its app version with the Cloud repository's deploy-stack command. -3. Turn on `enableGoogleWorkspaceConnector`. +- Organization slug `googletester`; the stack id is in staging fleet admin. + Agent `Workspace Tester` runs OpenCode on DeepSeek V4.1 Flash 1017 through + a company OpenRouter connection (a dedicated key with a spending limit). +- `enableGoogleWorkspaceConnector` is on through a fleet-admin override. +- It runs an app build from before the disconnect-revoke change, because no + Cloud composition existed yet for a newer commit. Redeploy, then test + disconnect. +- **Passed, on staging's default Google client and Google's MCP transport:** + picker and disclosure, a 10-scope request, consent, connection test calls + (list labels, search, read the synthetic email in full, create a draft), + "Delete data", and a real agent task that found the synthetic email by its + marker, returned the full body and left an unsent draft (about 2 minutes). +- **Not yet on the separate Google app.** That app is External, In + Production, 0 of 100 users, with the six REST APIs enabled and the staging + broker callback registered on its one web client. The staging environment + has the alternate client ID. Still needed, in this order: Dotta adds a + client secret and stores it as the one-time bootstrap secret, then the + stack list variable is set, then a staging deploy, then reconnect. Setting + the stack list before the secret exists fails every staging deploy. +- Reviewer password login for this host is supported by the broker but its + secret is not set yet. -Two obstacles (reported): +Found while testing: -- The broker cannot point one workspace at the separate Google app. Every - workspace in an environment uses that environment's one Google client. -- The scoped reviewer password login is hard-coded to the production tester. +- Google's live MCP server offered 34 of our 36 allowlisted actions on the + tester; `gmail__list_threads` and `gmail__search_messages` were missing. + `gmail__get_draft` was offered live even though Google's published + reference does not list it, so the reference and the live server differ. +- Write actions default to "Allowed" with no approval step. Dotta to decide. +- The connection audit page shows internal tool names and raw ids. +- The REST tools have not been run against real Google yet. Reviewer login: Google's reviewers could not use our normal sign-in, so we gave them **a custom password** for the Paperclip login. Any reviewer @@ -228,17 +246,22 @@ Known mismatches to clean up (after #22001 the app side matches the 14): ## Cloud broker (paperclip-cloud) -As reported by a read-only audit on November 17. Not re-verified here. +First reported by a read-only audit on November 17. The changes listed below +were then built and merged on November 17 and 18. They are live on **staging +only**; production still runs the old broker. - The profile registry is at `src/connections/providers.ts`. - One Google client per environment, shared by all profile groups. Staging's client differs from production's. - `workspace.all` is enabled on staging only. - There is no `gmail.archive` profile. -- A revoke endpoint exists, but every Google profile has revocation turned off. -- There is no per-workspace client override. +- Revocation is on for Google profiles, with a ledger of provider grants. +- A per-stack alternate Google client exists (for the tester). It is chosen + only from the enrolled stack id. +- The scoped reviewer password login allows the production and the staging + tester hosts. -Changes needed in the broker: +Changes made in the broker (staging): | Change | Why | | --- | --- | diff --git a/doc/plans/2026-11-17-google-workspace-production-checklist.md b/doc/plans/2026-11-17-google-workspace-production-checklist.md index d1a5ec00701..313e100301b 100644 --- a/doc/plans/2026-11-17-google-workspace-production-checklist.md +++ b/doc/plans/2026-11-17-google-workspace-production-checklist.md @@ -93,8 +93,8 @@ Decisions and the details behind them are kept in the - [ ] Each service switched to REST after a live test on the staging tester. - [ ] Scopes identical in the picker, the server, the Cloud broker and the Google Console. -- [ ] `googletester.staging.paperclip.app` created and wired to the new Google - app. +- [x] `googletester.staging.paperclip.app` created (Nov 18). +- [ ] Staging tester wired to the new Google app. ## 3. Policy and privacy