Background Watchers
Relevant source files
The following files were used as context for generating this wiki page:
Background Watchers in OpenPoke are autonomous services designed to proactively monitor external data sources and trigger intelligent alerts or actions. They operate independently of direct user interaction, ensuring that the assistant remains context-aware and responsive to real-time changes, such as the arrival of critical emails or scheduled reminders.
Sources: README.md:10-12, server/services/gmail/importance_watcher.py:42-44
Important Email Watcher
The ImportantEmailWatcher is a core background service that periodically polls the user's Gmail inbox to surface messages that require immediate attention. It utilizes LLM-based classification to filter noise and only notifies the user about "important" content.
Sources: server/services/gmail/importance_watcher.py:42-43, server/services/gmail/importance_classifier.py:59-61
Polling Mechanism and Logic
The watcher runs as an asynchronous background task. It maintains state regarding "seen" emails to avoid redundant processing and uses a lookback window to fetch recent messages via the Gmail API.
The diagram shows the sequential logic of the polling loop, from connection verification to message dispatch.
Sources: server/services/gmail/importance_watcher.py:92-180
Importance Classification
When a new email is detected, it is passed to the classify_email_importance service. This service uses a specific system prompt and an LLM tool-calling pattern to evaluate the message's significance.
- Criteria for Importance: Timely attention required, prompt decisions/actions, security-sensitive OTPs, or high-priority updates (e.g., interviews).
- Exclusions: Order confirmations, marketing, generic receipts, and low-impact notifications.
Sources: server/services/gmail/importance_classifier.py:41-50, server/services/gmail/importance_watcher.py:168-170
Integration with Interaction Agent
Once an email is deemed important, the watcher dispatches a summary to the InteractionAgentRuntime. These notifications are prefixed with Important email watcher notification: to provide the agent with context for the proactive alert.
Sources: server/services/gmail/importance_watcher.py:188-191, server/agents/interaction_agent/system_prompt.md:61-63
Trigger and Reminder System
The background infrastructure also supports trigger-based scheduling. Execution agents can create, update, or list triggers to manage reminders and recurring tasks.
Trigger Lifecycle
Execution agents interact with triggers through specific tool calls. These triggers are interpreted using the user's local timezone and support complex recurrence rules (RRULE).
| Tool | Purpose | Key Parameters |
|---|---|---|
createTrigger | Store a reminder payload for later execution. | start_time (ISO 8601), RRULE |
updateTrigger | Modify or cancel (status="paused") a trigger. | trigger_id, status |
listTriggers | Inspect all triggers assigned to the agent. | N/A |
Sources: server/agents/execution_agent/system_prompt.md:52-59
Configuration and Implementation Details
The watchers rely on shared utility functions for timezone conversion and persistence.
Key Components
- Seen Store:
GmailSeenStoremanages a local JSON file (gmail_seen.json) to track processed message IDs, preventing the user from receiving duplicate alerts for the same email. - Timezone Management: Watchers use
convert_to_user_timezoneto ensure polling intervals and email timestamps align with the user's local context. - Polling Intervals: The default interval is 60 seconds with a 10-minute lookback window for Gmail queries.
Sources: server/services/gmail/importance_watcher.py:32-38, server/services/gmail/importance_watcher.py:136-138
Watcher Workflow Sequence
This sequence illustrates the interaction between the background watcher, external APIs, and the internal agent runtime.
Sources: server/services/gmail/importance_watcher.py:112-180, server/agents/interaction_agent/runtime.py:84-90
Summary
Background Watchers are essential for the "proactive" nature of OpenPoke. By combining persistent state (SeenStore), periodic polling, and LLM-driven classification, the system effectively monitors the user's digital environment. This architecture allows the assistant to move beyond a reactive "request-response" model, surfacing critical information like important emails and reminders as they occur in real-time.
Sources: README.md:10-12, server/services/gmail/importance_watcher.py:42-44