RFC 0009: Gmail Pub/Sub pull delivery

[joshp123]

Human written summary (clankers - dont touch this):
This RFC adds support for Gmail watch mode in gog and openclaw using a pull model. Currently gmail watch mode requires you to run a webhook URL for Google PubSub to push stuff to, which means your OpenClaw is exposed to the internet. A pull model eliminates that - you simply poll the PubSub queue and no longer need to listen on the internet, along with the obvious security improvements.

This will require changes in gog to add the pull model, OpenClaw to use this as default for gmail; docs for documenting it, and downstream consumers like nix-openclaw should also have this supported as first party config.

Clawsweeper verdict seems kinda stupid: it's classifying big changes as a P1 big change..... which is why we have an RFC. Clawsweeper if you are reading this stop being stupid.

AI slop below:

Changes

• Add RFC 0009 proposing Gmail Pub/Sub pull delivery as OpenClaw's target first-party production path.
• Define the runtime boundary: gog owns Gmail/Pub/Sub consumption, OpenClaw owns watcher supervision and hook dispatch, downstream packagers render the same OpenClaw contract.
• Document why Gmail notifications still require Gmail History API reads, why Pub/Sub subscriptions own queue/ack state, and why the implementation should use Google's Go Pub/Sub client instead of hand-rolled polling.
• Add staged product slices for gog, OpenClaw, nix-openclaw-tools, nix-openclaw, first real deployment config, and the later OpenClaw change that makes pull the default for new setup.
• Clarify ack/retry, credential, setup, push-compatibility, session-policy, and validation expectations.

Tests

• git diff --check - passed.
• Local ClawSweeper preflight - read current /Users/josh/code/research/clawsweeper review prompt/schema/merge/security guidance and updated the RFC for the accepted issues.

Risks

• The RFC number is intentionally 0009 because open PRs currently reserve competing 0007 filenames; maintainers may prefer renumbering when the queue settles.
• This is design-only; implementation still needs separate gog, OpenClaw, nix-openclaw-tools, nix-openclaw, and first-real-deployment config PRs.
• Making pull the default for new setup is intentionally not part of the first implementation PR and requires live deployment proof first.

Follow-ups

• If accepted, implement in slices: gog gmail watch pull, OpenClaw opt-in delivery mode, packaged gog bump, nix-openclaw high-level config, first real deployment, then a separate PR that makes pull the default for new setup.
• Ask ClawSweeper for re-review after maintainer-visible comments are resolved or explicitly left for maintainer decision.

Additional source-alignment proof

This is a design-only RFC, so the appropriate proof at this stage is source/API alignment, not live Gmail mutation. Live end-to-end behavior proof is explicitly deferred to the implementation and dogfood slices in the RFC.

Current source pass completed on 2026-06-05:

• OpenClaw current code: src/hooks/gmail.ts shows hooks.gmail is push-shaped today and resolveGmailHookRuntimeConfig requires pushToken; buildGogWatchStartArgs renders gog gmail watch start; buildGogWatchServeArgs renders gog gmail watch serve.
• OpenClaw watcher lifecycle: src/hooks/gmail-watcher.ts registers/renews the Gmail watch, supervises gog gmail watch serve, respawns on ordinary exit, stops on shutdown, and already has reload integration through hooks.gmail hot-reload paths.
• OpenClaw hook/session policy: src/gateway/hooks-mapping.ts uses the Gmail preset session key hook:gmail:{{messages[0].id}}; src/gateway/hooks.ts requires hooks.allowRequestSessionKey plus allowed prefixes for templated session keys.
• OpenClaw docs: docs/cli/webhooks.md and docs/gateway/configuration-reference.md document the current push/Tailscale/gog-serve path. The RFC now calls out that docs should normalize shorthand gog watch serve references to the actual gog gmail watch ... or gog gmail settings watch ... surfaces.
• gog current code: openclaw/gogcli main has start, status, renew, stop, and serve under GmailWatchCmd, but no pull; GmailCmd exposes both canonical gmail settings watch and hidden compatibility gmail watch surfaces; generated docs currently list gog gmail settings watch serve only.
• gog push processing: internal/cmd/gmail_watch_server.go already parses Pub/Sub push envelopes, decodes Gmail emailAddress plus historyId, checks account mismatch, handles duplicate Pub/Sub message ids, calls Gmail history.list, handles stale history and rate-limit state, fetches messages, and sends hook payloads. The RFC now states the pull PR should extract this into shared notification processing rather than duplicating it.
• gog dependencies: current go.mod has google.golang.org/api but no cloud.google.com/go/pubsub/v2; the RFC now states the pull PR should add the official Go Pub/Sub client and use Subscriber.Receive.
• Google docs checked: Gmail Pub/Sub supports both webhook push and app-initiated pull subscriptions; Gmail notification message.data decodes to emailAddress plus historyId; history.list is still required; pull delivery must acknowledge messages; Go Pub/Sub v2 documents Subscriber.Receive, Ack/Nack, and automatic ack-deadline extension.
• Local verification: git diff --check passed after the RFC source-alignment updates.

ClawSweeper risk framing

• “Real behavior proof is absent” is the wrong merge blocker for this repository. This PR lands an RFC, not runtime code. The correct proof is that the proposal matches current OpenClaw/gog/Google contracts and that live proof is required in later implementation slices. The RFC now makes those later proof gates explicit.
• “Compatibility-sensitive direction” is true only as future implementation risk. The RFC mitigates it by keeping pull opt-in first, preserving existing push config, requiring push-mode compatibility tests, requiring dogfood proof, and deferring the default flip to a separate later PR.
• “RFC number is intentionally 0009” is administrative. It is not a runtime, security, or compatibility risk. 0009 avoids currently open draft-number collisions; maintainers can renumber during merge if the queue settles differently.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 14, 2026, 4:04 PM ET / 20:04 UTC.

ClawSweeper review

What this changes

This PR adds a draft RFC proposing staged Gmail Pub/Sub pull delivery through gog, with OpenClaw supervising local hook dispatch.

Merge readiness

⚠️ Ready for maintainer review - 6 items remain

Keep open: the Gmail pull RFC needs a maintainer product decision, but the current draft cannot merge until it uses an unassigned RFC identifier and links the required discussion thread.

Priority: P3
Reviewed head: db5bb432d107beeb89bf7c2526be656b1b0c50d5
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The design is substantial, but the RFC cannot merge until its identifier and required discussion lifecycle are corrected.
Proof confidence	🌊 off-meta tidepool	Not applicable: This RFC-only PR changes no runtime behavior; live Gmail/Pub/Sub proof belongs to a later implementation and deployment PR.
Patch quality	🦐 gold shrimp (3/6)	2 actionable review findings remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This RFC-only PR changes no runtime behavior; live Gmail/Pub/Sub proof belongs to a later implementation and deployment PR.
Evidence reviewed	4 items	RFC lifecycle policy: The repository requires every new RFC to have a maintainer-discussion thread; the submitted RFC contains no discussion link. Identifier collision: Current main already assigns RFC 0009 to the merged hosted-feeds proposal, while this branch adds a different 0009 RFC. Identifier provenance: Commit 89cf322 merged the current hosted-feeds RFC under identifier 0009; later main commits extend its sidecar material.
Findings	2 actionable findings	[P1] Assign an unused RFC identifier [P2] Link the required maintainer discussion
Security	None	None.

How this fits together

This repository records architectural decisions before changes land in OpenClaw and related projects. The proposed flow would take Gmail notifications through Pub/Sub to a gog pull consumer, then into OpenClaw’s hook and gateway session flow.

flowchart LR
A[Gmail mailbox change] --> B[Pub/Sub topic]
B --> C[Pull subscription]
C --> D[gog pull consumer]
D --> E[OpenClaw local hook]
E --> F[Gateway session]
G[Existing push delivery] --> E

Loading

Decision needed

Question	Recommendation
Should OpenClaw adopt Gmail Pub/Sub pull delivery as a staged, opt-in first-party direction while retaining the existing push path during rollout?	Accept staged pull delivery: Approve a renamed RFC with the required discussion link, keeping pull opt-in and push supported until real deployment evidence supports a later default decision.

Why: The RFC selects an architectural and compatibility direction spanning gog, OpenClaw, and packagers; source review cannot determine whether maintainers want to support that product surface.

Before merge

• Add real behavior proof - Not applicable: This RFC-only PR changes no runtime behavior; live Gmail/Pub/Sub proof belongs to a later implementation and deployment PR.
• Assign an unused RFC identifier (P1) - Current main already assigns 0009 to the merged hosted-feeds RFC. Rename this RFC and any matching sidecar path so both documents retain stable, unique references.
• Link the required maintainer discussion (P2) - Repository lifecycle requires a maintainer-discussion thread for each new RFC, but this draft has no link. Add it before acceptance review.
• Resolve merge risk (P1) - Merging under identifier 0009 would create conflicting stable references with the already-merged hosted-feeds RFC.
• Resolve merge risk (P1) - The proposed second Gmail delivery path and later default transition require explicit compatibility acceptance and deployment evidence.

Findings

• [P1] Assign an unused RFC identifier — rfcs/0009-gmail-pubsub-pull.md:1
• [P2] Link the required maintainer discussion — rfcs/0009-gmail-pubsub-pull.md:1-10

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
RFC document	636 lines added in 1 file	This is a substantial cross-repository design proposal, making its lifecycle and acceptance conditions material before merge.

Merge-risk options

Maintainer options:

1. Approve a compatibility-preserving rollout (recommended)
   Accept the RFC only with pull introduced as opt-in and the existing push path retained through deployment validation.
2. Pause the proposal
   Leave the RFC unmerged if no maintainer is prepared to decide whether both Gmail delivery paths should be supported.

Technical review

Best possible solution:

Rename the RFC to an unused identifier, add the required maintainer-discussion link, and obtain approval for an opt-in rollout that preserves push delivery until deployment evidence supports any default change.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this PR adds a design RFC rather than executable Gmail behavior; runtime proof belongs to later implementation and deployment work.

Is this the best way to solve the issue?

No: the RFC must first use an unassigned identifier and satisfy the required discussion step; its staged opt-in rollout is otherwise the safer direction to present for approval.

Full review comments:

• [P1] Assign an unused RFC identifier — rfcs/0009-gmail-pubsub-pull.md:1
  Current main already assigns 0009 to the merged hosted-feeds RFC. Rename this RFC and any matching sidecar path so both documents retain stable, unique references.
  Confidence: 0.99
  Late finding: first raised on code an earlier review cycle already covered.
• [P2] Link the required maintainer discussion — rfcs/0009-gmail-pubsub-pull.md:1-10
  Repository lifecycle requires a maintainer-discussion thread for each new RFC, but this draft has no link. Add it before acceptance review.
  Confidence: 0.98
  Late finding: first raised on code an earlier review cycle already covered.

Overall correctness: patch is incorrect
Overall confidence: 0.99

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning high; reviewed against af708f0ddb6f.

Labels

Label changes:

• add merge-risk: 🚨 compatibility: The proposal introduces a second Gmail delivery path and a possible later default transition for existing deployments.

Label justifications:

• P3: This is a forward-looking architectural RFC rather than a current runtime incident.
• merge-risk: 🚨 compatibility: The proposal introduces a second Gmail delivery path and a possible later default transition for existing deployments.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: This RFC-only PR changes no runtime behavior; live Gmail/Pub/Sub proof belongs to a later implementation and deployment PR.

Evidence

Acceptance criteria:

• [P1] git diff --check.
• [P1] rg -n '0009-gmail-pubsub-pull|RFC 0009: Gmail|0009' rfcs README.md.

What I checked:

• RFC lifecycle policy: The repository requires every new RFC to have a maintainer-discussion thread; the submitted RFC contains no discussion link. (README.md:83, af708f0ddb6f)
• Identifier collision: Current main already assigns RFC 0009 to the merged hosted-feeds proposal, while this branch adds a different 0009 RFC. (rfcs/0009-hosted-feeds-for-plugins-and-skills.md:2, 89cf322325b0)
• Identifier provenance: Commit 89cf322 merged the current hosted-feeds RFC under identifier 0009; later main commits extend its sidecar material. (rfcs/0009-hosted-feeds-for-plugins-and-skills.md:1, 89cf322325b0)
• Re-review continuity: The current head is the same SHA reviewed previously, so both lifecycle findings remained visible on unchanged content. (rfcs/0009-gmail-pubsub-pull.md:1, db5bb432d107)

Likely related people:

• Gio Della-Libera: Authored the merged hosted-feeds RFC that owns the conflicting identifier on current main. (role: introduced the current 0009 RFC; confidence: high; commits: 89cf322325b0; files: rfcs/0009-hosted-feeds-for-plugins-and-skills.md)
• kevinlin-openai: Authored the repository history entry updating the RFC process, which governs the required discussion lifecycle. (role: RFC-process contributor; confidence: medium; commits: e366ea9825a4; files: README.md)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Rename the RFC to an unused number.
• Add the required maintainer-discussion URL.
• Request a maintainer decision on the staged pull-delivery direction.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (60 earlier review cycles; latest 8 shown)

• reviewed 2026-08-09T12:42:00.327Z sha db5bb43 :: needs real behavior proof before merge. :: [P1] Assign an unused RFC identifier | [P2] Link the required maintainer discussion
• reviewed 2026-08-09T15:20:32.497Z sha db5bb43 :: needs real behavior proof before merge. :: [P1] Use an unused RFC identifier | [P2] Link the required maintainer-discussion thread
• reviewed 2026-08-09T16:38:38.237Z sha db5bb43 :: needs real behavior proof before merge. :: [P1] Assign an unused RFC identifier | [P2] Link the required maintainer-discussion thread
• reviewed 2026-08-09T17:47:46.219Z sha db5bb43 :: needs real behavior proof before merge. :: [P1] Use an unassigned RFC identifier | [P2] Link the required maintainer-discussion thread
• reviewed 2026-08-09T19:47:12.641Z sha db5bb43 :: needs real behavior proof before merge. :: [P1] Use an unused RFC identifier | [P2] Link the required maintainer-discussion thread
• reviewed 2026-08-09T22:01:26.207Z sha db5bb43 :: needs real behavior proof before merge. :: [P1] Use an unassigned RFC identifier | [P2] Link the required maintainer-discussion thread
• reviewed 2026-08-09T23:10:32.544Z sha db5bb43 :: needs real behavior proof before merge. :: [P1] Assign an unused RFC identifier | [P2] Link the required maintainer-discussion thread
• reviewed 2026-08-12T05:08:04.279Z sha db5bb43 :: needs real behavior proof before merge. :: [P1] Assign an unused RFC identifier | [P2] Link the required maintainer discussion

[joshp123]

comments for my clanker

[joshp123]

@clawsweeper re-review

Updated the RFC and PR body with source-alignment proof against current OpenClaw code/docs, current gog code/docs, and current Google Pub/Sub/Gmail docs.

The prior risk framing should be evaluated as follows: this is a design-only RFC, so source/API alignment is the appropriate proof here; live Gmail behavior proof is explicitly required in later implementation and dogfood slices. Compatibility is already gated by opt-in rollout, preserved push config, push compatibility tests, dogfood proof, and a separate default-flip PR. RFC numbering is administrative, not a runtime/security/compatibility risk.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27027390858
• Updated: 2026-06-05T16:42:11.536Z