Customer Prompt Task

Relevant source files

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

• src/tasks/customerPromptTask.ts
• src/recoup/fetchTask.ts
• README.md
• AGENTS.md
• types/database.types.ts

The Customer Prompt Task is a background worker system designed to execute user-defined AI prompts on a scheduled basis. Integrated within the Trigger.dev v4 framework, this system bridges the Recoup Tasks API with a chat generation engine, allowing for automated, personalized customer interactions or internal task processing.

The task is triggered via dynamic schedules and is responsible for fetching specific task configurations, validating those configurations against Zod schemas, and initiating a chat generation process within a designated "room" associated with an artist and account.
Sources: src/tasks/customerPromptTask.ts:16-18, README.md:28-28, AGENTS.md:38-38

System Architecture

The Customer Prompt Task operates as a scheduled worker. It follows a linear execution flow that involves external API communication and multi-tenant context setting.

Data Flow Overview

The process begins when Trigger.dev executes the customer-prompt-task. The task uses an externalId provided by the schedule to fetch the full task configuration from the Recoup API. Once validated, it identifies or creates a roomId to scope the AI's response.

The diagram above illustrates the high-level logic of the task execution from trigger to completion.
Sources: src/tasks/customerPromptTask.ts:22-83, src/recoup/fetchTask.ts:31-86

Core Components

1. Task Fetching & Validation

The system relies on the fetchTask utility to retrieve data from the Recoup Tasks API (/api/tasks). The retrieved data is validated using taskResponseSchema to ensure it contains required fields like account_id, prompt, and schedule.

Field	Type	Description
id	string	The unique identifier for the task.
title	string	The display name of the task.
prompt	string	The instruction set for the AI model.
account_id	string	The owner account.
artist_account_id	string	The associated artist profile.
model	string (optional)	The specific AI model to use for generation.

Sources: src/recoup/fetchTask.ts:6-21, src/tasks/customerPromptTask.ts:36-49

2. Room & Context Management

Before generating a chat, the task must resolve a roomId. This ensures the conversation history is persistent and correctly scoped to the artist and account. The task also uses Trigger.dev tags to associate the execution with a specific account for logging and filtering.
Sources: src/tasks/customerPromptTask.ts:63-71

3. Chat Generation

The final step involves the generateChat function. This component takes the validated prompt and metadata to produce a response via the Recoup Chat API. If no prompt is provided in the configuration, the system uses a fallback: "Draft a friendly check-in message for our customers.".
Sources: src/tasks/customerPromptTask.ts:56-58, src/tasks/customerPromptTask.ts:77-83

Technical Implementation

The task is defined using the Trigger.dev schedules.task factory. It accepts a TaskPayload containing timestamps and an externalId.

export const customerPromptTask = schedules.task({
  id: "customer-prompt-task",
  run: async (payload: TaskPayload) => {
    // 1. Fetch from Recoup API
    const rawTask = await fetchTask(payload.externalId);
    
    // 2. Validate with Zod
    const validationResult = chatSchema.safeParse(rawTask);
    
    // 3. Set multi-tenant context
    await tags.add(`account:${accountId}`);
    
    // 4. Resolve room and execute
    await generateChat({ prompt, accountId, roomId, artistId, model });
  }
});

Sources: src/tasks/customerPromptTask.ts:18-83

Related Database Entities

While the task interacts primarily with APIs, the underlying data structure is reflected in the system's database schema, specifically involving accounts, artists, and tasks.

Table	Relation	Usage in Task
accounts	Owner	Provides accountId for scoping and tagging.
tasks	Config	Stores the original prompt and schedule.
rooms	Context	Links the chat output to a specific conversation topic.

Sources: types/database.types.ts:167-175, types/database.types.ts:983-993, types/database.types.ts:1498-1512

Summary

The Customer Prompt Task serves as the execution engine for scheduled AI instructions within the Recoup ecosystem. By utilizing dynamic scheduling and centralized configuration fetching, it enables scalable, automated communication tailored to specific artist and customer contexts.