feat: add OpenAI OAuth, strict model overrides, and Gmail pull mode

README.md

@@ -458,14 +458,22 @@ The monitor sends a notification when failures reach the configured threshold an
 
 ## Gmail Pub/Sub Watcher
 
-Monitor a Gmail inbox via Google Cloud Pub/Sub push notifications. New emails trigger the agent pipeline and route responses to a configured output channel. Falls back to polling when push notifications are unavailable.
+Monitor a Gmail inbox and forward new messages into the agent pipeline.
+
+Supported delivery modes:
+- **Push** (Gmail watch → Pub/Sub topic → HTTP push subscription → `POST /gmail/push`)
+- **Pull** (Pub/Sub pull subscription → Flynn periodically pulls messages; no inbound webhook)
+- **Polling** (Gmail History API polling fallback)
 
 ### Prerequisites
 
-1. Create a Google Cloud project with the Gmail API and Pub/Sub API enabled
+1. Create a Google Cloud project with the Gmail API enabled
 2. Create OAuth2 credentials (Desktop application type) and download the JSON file
-3. Create a Pub/Sub topic (e.g. `projects/your-project/topics/gmail-push`)
-4. Run `flynn gmail-auth` to complete the OAuth2 flow and store the refresh token
+3. Run `flynn gmail-auth` to complete the OAuth2 flow and store the refresh token
+
+For Pub/Sub delivery (push/pull), also enable the Pub/Sub API and create:
+- A topic (e.g. `projects/your-project/topics/gmail-push`)
+- A subscription (push and/or pull)
 
 ### Configuration
 
@@ -475,6 +483,16 @@ automation:
     enabled: true
     credentials_file: ~/.config/flynn/gmail-credentials.json
     token_file: ~/.config/flynn/gmail-token.json   # Default location
+
+    # Push mode (optional)
+    pubsub_topic: projects/your-project/topics/gmail-push
+    disable_push: false
+
+    # Pull mode (optional; no inbound webhook required)
+    pubsub_subscription_id: projects/your-project/subscriptions/gmail-pull
+    pubsub_pull_interval: "60s"
+    pubsub_max_messages: 10
+
     watch_labels: [INBOX]                           # Labels to watch
     poll_interval: "60s"                            # Polling fallback interval
     message: "New email from {{from}}: {{subject}}\n\n{{snippet}}"
@@ -485,6 +503,8 @@ automation:
 
 Push notifications arrive at `POST /gmail/push` on the gateway HTTP server (bypasses gateway auth).
 
+Pull mode uses Application Default Credentials (e.g. `GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json`) to access Pub/Sub.
+
 ### Gmail Config Fields
 
 | Field | Required | Description |
@@ -492,8 +512,13 @@ Push notifications arrive at `POST /gmail/push` on the gateway HTTP server (bypa
 | `enabled` | no | Enable the Gmail watcher (default: `false`) |
 | `credentials_file` | yes | Path to Google OAuth2 credentials JSON |
 | `token_file` | no | Path to stored OAuth2 refresh token (default: `~/.config/flynn/gmail-token.json`) |
+| `pubsub_topic` | no | Pub/Sub topic for Gmail watch push notifications (`projects/<project>/topics/<topic>`) |
+| `disable_push` | no | Disable watch registration even if `pubsub_topic` is set (default: `false`) |
+| `pubsub_subscription_id` | no | Pub/Sub pull subscription (`projects/<project>/subscriptions/<sub>`) |
+| `pubsub_pull_interval` | no | How often to pull subscription messages (default: `60s`) |
+| `pubsub_max_messages` | no | Max messages per pull cycle (default: `10`) |
 | `watch_labels` | no | Gmail labels to watch (default: `[INBOX]`) |
-| `poll_interval` | no | Polling fallback interval: `60s`, `5m` (default: `60s`) |
+| `poll_interval` | no | Polling fallback interval: `60s`, `5m` (default: `300s`) |
 | `history_start` | no | ISO date string — only process emails received after this date |
 | `message` | no | Template for the agent message (default: `New email from {{from}}: {{subject}}\n\n{{snippet}}`) |
 | `output.channel` | yes | Channel name to route the response (e.g. `telegram`) |