From e51ca97ce4988335fc63dc7d8b745d452058e4df Mon Sep 17 00:00:00 2001 From: William Valentin Date: Sun, 22 Feb 2026 22:25:10 -0800 Subject: [PATCH] docs(gmail): document filter creation support --- README.md | 12 ++++++++++++ config/default.yaml | 2 ++ docs/plans/state.json | 21 ++++++++++++++++++++- 3 files changed, 34 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 0b0bb08..6005dc9 100644 --- a/README.md +++ b/README.md @@ -1154,6 +1154,7 @@ Supported delivery modes: 1. Create a Google Cloud project with the Gmail API enabled 2. Create OAuth2 credentials (Desktop application type) and download the JSON file 3. Run `flynn gmail-auth` to complete the OAuth2 flow and store the refresh token + - Requests scopes for both mailbox reads and filter management (`gmail.readonly` + `gmail.settings.basic`) For Pub/Sub delivery (push/pull), also enable the Pub/Sub API and create: - A topic (e.g. `projects/your-project/topics/gmail-push`) @@ -1208,6 +1209,17 @@ Pull mode uses Application Default Credentials (e.g. `GOOGLE_APPLICATION_CREDENT | `output.channel` | yes | Channel name to route the response (e.g. `telegram`) | | `output.peer` | yes | Peer/chat ID on the output channel | +### Gmail Tools + +When `automation.gmail.enabled: true`, Flynn registers Gmail tools: + +- `gmail.list` — list recent messages by label +- `gmail.search` — query messages with Gmail search syntax +- `gmail.read` — fetch full message body by ID +- `gmail.filter.create` — create Gmail filters (criteria + actions like archive/label/forward) + +`gmail.filter.create` requires a token with `gmail.settings.basic`. If your token was created before this scope was added, re-run `flynn gmail-auth`. + ### Template Variables | Variable | Description | diff --git a/config/default.yaml b/config/default.yaml index 5d151b5..c6ffa24 100644 --- a/config/default.yaml +++ b/config/default.yaml @@ -451,6 +451,8 @@ memory: # enabled: false # credentials_file: ~/.config/flynn/gmail-credentials.json # token_file: ~/.config/flynn/gmail-token.json +# # Authenticate with: flynn gmail-auth +# # (requests gmail.readonly + gmail.settings.basic for gmail.filter.create support) # # # Optional Pub/Sub delivery # # Push mode: configure a topic and a push subscription that POSTs to /gmail/push diff --git a/docs/plans/state.json b/docs/plans/state.json index 599da19..469cdff 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -3,6 +3,24 @@ "updated_at": "2026-02-23", "description": "Tracks the status of all Flynn plans and implementation phases", "plans": { + "gmail-filter-creation-tooling": { + "status": "completed", + "date": "2026-02-23", + "updated": "2026-02-23", + "summary": "Added Gmail filter creation support via new `gmail.filter.create` tool with criteria/action validation and OAuth scope guidance. Updated tool policy allowlists/groups and expanded `flynn gmail-auth` scopes to include `gmail.settings.basic` so filter creation works with newly-issued tokens.", + "files_modified": [ + "src/tools/builtin/gmail.ts", + "src/tools/builtin/gmail.test.ts", + "src/tools/policy.ts", + "src/tools/policy.test.ts", + "src/cli/gmail-auth.ts", + "src/cli/gmail-auth.test.ts", + "README.md", + "config/default.yaml", + "docs/plans/state.json" + ], + "test_status": "pnpm test:run src/tools/builtin/gmail.test.ts src/tools/policy.test.ts src/cli/gmail-auth.test.ts + pnpm typecheck passing" + }, "searxng-fallback-runtime-endpoint-doc-clarity": { "status": "completed", "date": "2026-02-23", @@ -6255,7 +6273,7 @@ } }, "overall_progress": { - "total_test_count": 1952, + "total_test_count": 1958, "all_tests_passing": true, "p0_completion": "3/3 (100%)", "p1_completion": "4/4 (100%)", @@ -6274,6 +6292,7 @@ "operator_dx_milestone": "Phase 3 (Live Ops Dashboard): 2/2 plans complete — milestone done", "dashboard_observability": "completed — service health graphs + core service log viewer added to web UI via observability RPCs and bounded backend sampling", "gmail_auth_cli": "flynn gmail-auth command implemented with OAuth2 flow, doctor check, config routed to Telegram", + "gmail_filter_creation": "completed — gmail.filter.create tool added with criteria/action validation; gmail-auth now requests gmail.settings.basic for filter-management permissions", "native_audio_support": "completed — smart routing for native audio (Gemini/OpenAI/GitHub) vs Whisper transcription fallback, plus 2026-02-23 arg hydration hardening, tool.args_rewritten audit metric, transient fetch retry/timeout hardening, localhost->127.0.0.1 fallback for transcription endpoint connectivity, and whisper docker-compose entrypoint arg fix for port 18801", "remaining_phases_completion": "Phase 1: 3/3 (100%) — context levels, command registry, memory structure. Phase 2: 3/3 (100%) — component registry, confidence routing, history index. Phase 3: 2/2 (100%) — adaptive memory/compaction, truthfulness/autonomy hardening", "next_up": "Track OpenClaw evolution regularly for inspiration and feature ideas"