Chat Session Management

Relevant source files

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

• src/chats/getTaskRoomId.ts
• src/tasks/customerPromptTask.ts
• src/schemas/chatSchema.ts
• src/recoup/fetchTask.ts
• types/database.types.ts

Chat Session Management is a core system within the Recoup platform designed to orchestrate automated interactions between AI models and users (accounts) or artists. It handles the lifecycle of a chat session, specifically by managing "rooms" where conversations persist, validating session configurations via structured schemas, and fetching task-specific metadata from the Recoup API.

The system ensures that automated background tasks, such as customer check-ins or scheduled artist updates, are routed to the correct conversational context. By utilizing unique identifiers for accounts, artists, and rooms, the system maintains historical continuity and prevents fragmented communication.
Sources: src/tasks/customerPromptTask.ts:1-74, src/chats/getTaskRoomId.ts

Core Data Models and Schema

Chat sessions are governed by strict data structures to ensure consistency across background tasks and the Recoup Chat API.

Session Configuration

The ChatConfig type defines the parameters required to initialize or resume a chat session. This includes identification for the owner (accountId), the subject (artistId), the specific interface (roomId), and the underlying AI model to be used.
Sources: src/schemas/chatSchema.ts:6-14

Field	Type	Description
prompt	string	The message text or instruction to be sent in the chat.
accountId	string	The unique identifier for the user account.
roomId	string	The unique identifier for the specific conversation room.
artistId	string	(Optional) The unique identifier for an artist associated with the chat.
model	string	(Optional) The specific AI model designated for the task.
Sources: src/schemas/chatSchema.ts:6-14, src/recoup/fetchTask.ts:54-59

Database Entities

Chat session persistence relies on several tables within the public schema of the database.

The diagram shows the relationship between conversational rooms, the persistent memory content stored within those rooms, and the associated accounts.
Sources: types/database.types.ts:1086-1107, types/database.types.ts:1537-1555

Room Identification and Retrieval

A critical component of session management is the retrieval of a valid roomId. Automated tasks use the getTaskRoomId utility to ensure that messages are posted to the intended location.

Resolution Logic

The system follows a priority-based logic to resolve a room:

1. If a roomId is explicitly provided in the task configuration, it is used directly.
2. If only IDs are available, the system attempts to find or create a room associated with the accountId and artistId.
3. If the resolution fails, the task is aborted to prevent orphaned messages.
   Sources: src/chats/getTaskRoomId.ts, src/tasks/customerPromptTask.ts:57-65

The flowchart illustrates how the system determines which room to use for an automated chat session.
Sources: src/tasks/customerPromptTask.ts:19-74

Automated Session Orchestration

Automated sessions are triggered via scheduled tasks (e.g., customer-prompt-task). These tasks integrate session management with external API fetches.

Workflow Execution

1. Fetch Task: The system calls the Recoup Tasks API (/api/tasks) using an externalId to retrieve the task configuration.
2. Validation: The raw response is validated against taskResponseSchema.
3. Session Setup: tags are added to the Trigger.dev execution context to categorize the session by accountId.
4. Message Generation: The system calls generateChat with the resolved roomId, prompt, and metadata.
   Sources: src/recoup/fetchTask.ts:32-75, src/tasks/customerPromptTask.ts:26-74

Recoup Tasks API Mapping

When fetching tasks, the internal API maps standard database fields to the ChatConfig used for session management.

// Mapping logic from src/recoup/fetchTask.ts
return {
  prompt: task.prompt,
  accountId: task.account_id,
  artistId: task.artist_account_id,
  model: task.model ?? undefined,
};

Sources: src/recoup/fetchTask.ts:67-72

Error Handling and Logging

Session management includes specialized logging for troubleshooting communication failures. The error_logs table specifically tracks issues related to room_id, allowing developers to trace errors back to specific conversational sessions. Captured data includes the error_message, stack_trace, and the last_message processed before the error occurred.
Sources: types/database.types.ts:1016-1051

Log Field	Description
room_id	Links the error to the specific chat session.
tool_name	Identifies which AI tool was active during the failure.
raw_message	The original payload that triggered the session error.
Sources: types/database.types.ts:1016-1051