Pulse Email Processing

Relevant source files

The following files were used as context for generating this wiki page:

• src/pulse/executePulseInSandbox.ts
• src/tasks/sendPulsesTask.ts
• src/tasks/sendPulseTask.ts
• src/recoup/fetchActivePulses.ts
• src/pulse/tagPulseEmailId.ts

Pulse Email Processing is a core background system responsible for generating and delivering personalized daily email digests to Recoup users. The system surfaces the most relevant information—including artist social metrics, recent conversation context, and updates from connected services like Google Drive—to provide actionable insights. It operates as a multi-stage pipeline using Trigger.dev tasks and ephemeral sandboxes to ensure secure and isolated content generation.

Sources: src/tasks/sendPulsesTask.ts:5-10, src/tasks/sendPulsesTask.ts:133-138

System Architecture

The Pulse system follows a hierarchical task execution model. A parent "orchestrator" task identifies eligible accounts and triggers individual "processor" tasks for each account. These processor tasks interface with external APIs to execute logic within isolated Linux microVM sandboxes.

Core Components

Component	Responsibility
sendPulsesTask	Orchestrates the daily run. Fetches active subscriptions and triggers batch processing.
sendPulseTask	Handles the execution lifecycle for a single account, including sandbox management and post-execution tagging.
Sandbox Environment	An isolated microVM where the actual data gathering, analysis, and email formatting logic (OpenClaw) occurs.
Recoup API	Provides endpoints for sandbox creation (/api/sandboxes) and fetching active pulse data.

Sources: src/tasks/sendPulsesTask.ts:138-164, src/tasks/sendPulseTask.ts:12-25, src/pulse/executePulseInSandbox.ts:35-42

High-Level Workflow

The following diagram illustrates the lifecycle of a Pulse generation run:

The workflow begins with a scheduled trigger that flows through batch execution to isolated sandbox environments.
Sources: src/tasks/sendPulsesTask.ts:133-157, src/tasks/sendPulseTask.ts:12-25

Logic and Execution Pipeline

Pulse processing logic is defined by a comprehensive system prompt that guides the AI agent within the sandbox through five distinct steps.

Step 1: Context Gathering

The system retrieves data from multiple sources over the past 7 days:

• User conversations (get_chats).
• Artist lists (get_artists).
• Connected tools via Composio (Google Drive, Docs, Sheets).

Sources: src/tasks/sendPulsesTask.ts:10-15

Step 2: Priority Determination

Artists are prioritized if they appear in recent conversations, have upcoming deadlines, or have recent releases. "Highest Priority" is assigned to artists appearing in both conversation data and recent activity logs.

Sources: src/tasks/sendPulsesTask.ts:17-26

Step 3: Deep Data Retrieval

For the top 1–3 priority artists, the system fetches:

• Social statistics (get_artist_socials).
• Metric changes.
• Artist images via Google Images.
• Documents from connected services using COMPOSIO_MULTI_EXECUTE_TOOL.

Sources: src/tasks/sendPulsesTask.ts:28-46

Step 4: Actionable Insights

The system completes one of three actions for each priority:

1. Report real streaming/social data.
2. Complete unfinished work (research/drafts).
3. Surface specific actionable insights.
   Fallback: If no priority data is found, the system searches for music industry news relevant to the user's genre.

Sources: src/tasks/sendPulsesTask.ts:48-54

Step 5: Email Formatting

The final output is an HTML email structured for mobile responsiveness.

The email generation follows strict "Conditional Elements Rules" to ensure no broken images or dead links are included.
Sources: src/tasks/sendPulsesTask.ts:58-100

Sandbox Execution Technical Details

The execution of the pulse logic is decoupled from the main task runner via a Sandbox API.

Sandbox Interface

The executePulseInSandbox function communicates with the Recoup API to provision environments.

Parameter	Type	Description
accountId	string	The unique identifier for the target account.
prompt	string	The full instructions (DEFAULT_PULSE_PROMPT) for the agent.

API Endpoint: POST ${NEW_API_BASE_URL}/api/sandboxes
Authentication: x-api-key header using RECOUP_API_KEY.

Sources: src/pulse/executePulseInSandbox.ts:35-56

Task Definitions

sendPulsesTask (Orchestrator)

• ID: send-pulses-task
• Schedule: 0 9 * * * (Daily 9 AM ET).
• Functionality: Calls fetchActivePulses() and uses sendPulseTask.batchTriggerAndWait() to process accounts in parallel.

sendPulseTask (Processor)

• ID: send-pulse-task
• Functionality: Calls executePulseInSandbox. Upon success, it invokes tagPulseEmailId to associate the sandbox run with a specific email record for tracking.

Sources: src/tasks/sendPulsesTask.ts:133-145, src/tasks/sendPulseTask.ts:12-25

Data Models and Schemas

The system uses Zod for validating API responses from the sandbox environment.

const sandboxEntrySchema = z.object({
  sandboxId: z.string(),
  sandboxStatus: z.enum(["pending", "running", "stopping", "stopped", "failed"]),
  timeout: z.number(),
  createdAt: z.string(),
  runId: z.string().optional(),
});

Sources: src/pulse/executePulseInSandbox.ts:5-11

Conclusion

Pulse Email Processing represents a sophisticated integration of scheduled background tasks, AI-driven data synthesis, and isolated code execution. By leveraging sandboxes, Recoup ensures that the complex logic of searching social metrics and private documents is performed securely, while the Trigger.dev framework provides robust orchestration and error handling for large-scale daily distributions.