Skip to content

feat(gmail): resolve web URL view tokens to API IDs - #1327

Open
srnnkls wants to merge 2 commits into
openclaw:mainfrom
srnnkls:feat/gmail-view-token
Open

srnnkls wants to merge 2 commits into
openclaw:mainfrom
srnnkls:feat/gmail-view-token

Conversation

@srnnkls

@srnnkls srnnkls commented Nov 10, 2026

Copy link
Copy Markdown

Summary

Current Gmail web URLs carry an opaque view token instead of the hex ID:

https://mail.google.com/mail/u/0/#inbox/FMfcgz…

Passing such a URL or token to gmail thread get, gmail get, etc. fails with 400 invalidArgument: Invalid id value, because normalizeGmailThreadID / normalizeGmailMessageID only recognise hex IDs.

The token is a base64 string re-encoded in the consonant-only base-40 alphabet BCDFGHJKLMNPQRSTVWXZbcdfghjklmnpqrstvwxz. Its payload is f:<decimal> or thread-f:<decimal> for threads and msg-f:<decimal> for messages; the decimal is the API ID. This PR decodes the token offline (no API call) in the existing normalizers, both for bare tokens and for the last fragment segment of a Gmail URL. Thread tokens only resolve in thread normalization and msg-f tokens only in message normalization; anything that does not decode to a known prefix is passed through unchanged as before.

The scheme matches the Gmail parser in Unfurl.

User-facing change

Gmail commands that take a thread or message ID now also accept current Gmail web URLs and their bare view tokens. No new flags.

Testing

  • webid_test.go: thread and message cases for bare tokens, #inbox/… and #label/…?compose=new URLs, the thread-f: variant, cross-kind rejection (a msg-f token is not a thread ID and vice versa), and a non-decodable consonant string. The new cases fail on main and pass with this change.
  • Verified against a real #inbox/FMfcgz… URL from my mailbox: it decodes to the hex ID that gmail search returns for the same message, and gog gmail thread get <hex> fetches it.
  • make fmt-check lint deadcode test docs-check agent-skills-check all pass locally (one earlier make test run reported a FAIL that did not reproduce on rerun; the keyring timeout tests seemed to be the flaky part).

Current Gmail web URLs carry an opaque view token (#inbox/FMfcgz...)
instead of the hex thread ID, so pasting them into thread/message
commands fails with 400 Invalid id value. The token is a base64 string
re-encoded in a consonant-only base-40 alphabet whose payload is
f:/thread-f:/msg-f:<decimal id>; decode it offline in the existing
Gmail ID normalizers.
Copilot AI balanced review requested due to automatic review settings November 10, 2026 09:50
@clawsweeper

clawsweeper Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

@clawsweeper clawsweeper Bot added clawsweeper:intake:feature Preliminary submission classification; full source review pending. P2 Normal priority bug or improvement with limited blast radius. rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. and removed clawsweeper:intake:feature Preliminary submission classification; full source review pending. labels Nov 10, 2026
@clawsweeper

clawsweeper Bot commented Nov 10, 2026

Copy link
Copy Markdown
Contributor

Codex review: needs real behavior proof before merge.

What this changes

This PR decodes Gmail web view tokens into hexadecimal API IDs in the shared thread and message normalizers.

Example: Pass https://mail.google.com/mail/u/0/#inbox/FMfcgzGwHpVzSvQjBWlWNGBCZqCPPPMN to gmail thread get.

  • Before: The URL passes through unchanged and is submitted as the thread ID.
  • After: The normalizer supplies thread ID 18c0abc123def456.

Review scores

Measure Result What it means
Overall readiness 🧂 unranked krab (1/6) The focused implementation appears sound apart from a minor repository-policy correction, but the required changed-behavior proof is insufficient.
Proof confidence 🧂 unranked krab (1/6) Real behavior proof is necessary before merge. See Before merge.
Patch quality 🐚 platinum hermit (4/6) 1 actionable review finding remain.

Product

Kind: Bug fix · Worth it: Yes · Fix scope: Complete
User problem: Pasting a current Gmail thread URL into an ID-taking command fails because its opaque token is not converted to the API ID.
Reason: This repairs the existing Gmail URL-input capability in its shared owner, preserves established inputs and defaults, and keeps thread tokens distinct from message tokens.

Merge readiness

⛔ Blocked before merge - 2 items remain

Keep this PR open: current main still lacks opaque Gmail token decoding, and the focused implementation addresses that gap; one changelog policy correction remains.

Priority: P2
Reviewed head: 85a6d5da6ad0ccdfaa1b131a2a478cdd86d06782

Before merge

  • Add real behavior proof - The body reports offline decoding and a successful gog gmail thread get &lt;hex> call, which bypasses the changed token-input path. No supplied artifact shows the patched CLI accepting an opaque URL or token and retrieving the matching resource. Please add terminal output, a terminal screenshot, or redacted logs for that path, covering thread and message decoding; redact IPs, API keys, phone numbers, and non-public endpoints. After adding proof, update the PR body, then request a new review with @clawsweeper re-review. The PR author or someone with repository write access can request it.
  • Credit the contributor in the Unreleased entry (P3) - The added user-visible changelog entry includes the PR reference but omits contributor thanks, which the root AGENTS.md explicitly requires. Add thanks to @srnnkls in this entry.

Findings

  • [P3] Credit the contributor in the Unreleased entry — CHANGELOG.md:5

Tests

  • Missing end-to-end proof: Provide a shipped-CLI run accepting an opaque thread URL and a message token with matching returned IDs; the reported base-fail/head-pass tests are not demonstrated by supplied output.
Agent review details

How this fits together

Gmail CLI commands pass user-supplied IDs and URLs through shared normalizers before authenticated Gmail API requests; this change adds offline token decoding at that existing boundary.

flowchart LR
  A[CLI ID or Gmail URL] --> B[Shared ID normalizer]
  B --> C[Existing hexadecimal extraction]
  B --> D[Opaque token decoder]
  C --> E[Thread or message API ID]
  D --> E
  E --> F[Authenticated Gmail API request]
Loading

Technical review

Best possible solution:

Extend the existing shared normalizers with resource-specific offline decoding while preserving hexadecimal IDs and unchanged fallback behavior.

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

Source establishes the failure path: current main returns an opaque-token URL unchanged, and thread retrieval sends that value as the Gmail API ID; no target code was executed.

Is this the best way to solve the issue?

The shared normalizers are the appropriate owner, and the decoding algorithm matches the contributor-cited reference without adding dependencies, flags, or a competing resolution path.

Full review comments:

  • [P3] Credit the contributor in the Unreleased entry — CHANGELOG.md:5
    The added user-visible changelog entry includes the PR reference but omits contributor thanks, which the root AGENTS.md explicitly requires. Add thanks to @srnnkls in this entry.
    Confidence: 1
    Late finding: first raised on code an earlier review cycle already covered.

Overall correctness: patch is correct
Overall confidence: 0.91

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against e8428c36dd31.

Provenance checked

Testing

Proof path: unit tests only.

Security

None.

Evidence

Acceptance criteria:

  • git diff --check
  • git diff -- CHANGELOG.md

What I checked:

  • Current main still lacks the behavior: The verified default branch remains e8428c3; its normalizers recognize hexadecimal URL IDs but contain no opaque-token decoder. (internal/cmd/webid.go:15, e8428c36dd31)
  • Pinned introduced change: The introduced diff adds decoding to both existing normalizers, preserves hexadecimal handling, restricts decoded payloads by resource kind, and adds fixed input/output cases. (internal/cmd/webid.go:122, 85a6d5da6ad0)
  • Production call path: Thread retrieval normalizes the supplied ID before Users.Threads.Get("me", threadID); message retrieval and mutation consumers also use the shared normalizers. (internal/cmd/gmail_thread.go:38, 85a6d5da6ad0)
  • Feature provenance: Commit 3371e3f added webid.go in merged feat(cli): agent ergonomics + gmail watch exclude labels #201 as part of CLI ergonomics and URL normalization; this PR extends that existing owner. (internal/cmd/webid.go:15, 3371e3f3ad6d)
  • Contributor-cited decoding reference: The PR explicitly cites Unfurl as its format reference, establishing the relevant external contract. Its Gmail parser uses the same base-40 alphabet and base64 conversion and identifies f:<decimal> as a thread payload; the repository tree contains no AGENTS.md. (unfurl/parsers/parse_gmail.py:67, 31600b855bdb)
  • Discussion and supplied validation: The complete body reports decoding a mailbox URL and fetching its hexadecimal ID, but supplies no terminal output or artifact showing a token or URL passed through the changed CLI. Both comments are automation status messages and the review records no substantive review. (85a6d5da6ad0)

Likely related people:

  • salmonumbrella: Raw commit 3371e3f adds internal/cmd/webid.go:12 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 3371e3f3ad6d; files: internal/cmd/webid.go)

Preflight source

Source unknown. Source comparison at the observed PR snapshot only. Completion is self-reported; body, policy, tests, execution, and report bytes are not verified.

Review metrics

Metric Value Why it matters
Change size Production +76/-0; tests +9/-0; changelog +2/-0 The implementation remains in the existing shared normalization file, with table cases covering decoding, URL extraction, resource separation, and invalid input.

Labels

Label changes:

  • add P2: Current Gmail URL input fails in an existing CLI workflow, while hexadecimal API IDs remain usable.
  • add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
  • add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask.

Label justifications:

  • P2: Current Gmail URL input fails in an existing CLI workflow, while hexadecimal API IDs remain usable.
  • rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
  • status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

Reviewed November 10, 2026, 5:05 AM ET / 10:05 UTC.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

P2 Normal priority bug or improvement with limited blast radius. rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants