feat(workflow-agent): add email sending pattern knowledge to workflow and chat agents

[larryro]

Problem

The chat agent and workflow assistant agent don't know how to create email-sending workflows because:

1. The email sending pattern (conversation → approval → auto-send) is NOT documented
2. Agents look for a send_email action that doesn't exist
3. No documentation explains that conversation metadata + approval = automatic email sending
4. The product_recommendation_email.ts example exists but agents don't know to reference it

Current Working Pattern (Already Implemented)

1. conversation action (operation: 'create') → stores email in metadata
2. approval action (operation: 'create_approval') → resourceType: 'conversations'
3. User approves → sendMessageViaEmail() auto-triggers → email sent

Solution: Document the Pattern for Agents

Files to Modify

1. Update Workflow Syntax Documentation

File: services/platform/convex/workflow/workflow_syntax_compact.ts

Add new section "Email Sending Pattern":

## EMAIL SENDING PATTERN

To send emails via workflows, use the conversation + approval pattern:

### Step 1: Create Conversation with Email Metadata
{
  stepType: 'action',
  config: {
    type: 'conversation',
    parameters: {
      operation: 'create',
      customerId: '{{customerId}}',
      subject: '{{emailSubject}}',
      channel: 'email',
      direction: 'outbound',
      metadata: {
        emailSubject: '{{emailSubject}}',
        emailBody: '{{emailBody}}',        // HTML content
        emailPreview: '{{emailPreview}}',  // Preview text
        customerEmail: '{{customerEmail}}', // Recipient
      },
    },
  },
}

### Step 2: Create Approval for Email Review
{
  stepType: 'action',
  config: {
    type: 'approval',
    parameters: {
      operation: 'create_approval',
      resourceType: 'conversations',
      resourceId: '{{steps.create_conversation.output.data._id}}',
      description: 'Review email before sending',
      metadata: {
        customerEmail: '{{customerEmail}}',
        emailBody: '{{emailBody}}',
      },
    },
  },
}

### How It Works
- Approval appears in dashboard for human review
- When user approves, system automatically sends the email
- Email sent via organization's default email provider
- Conversation tracks the email thread for replies

### Required Metadata Fields
- emailSubject: Email subject line
- emailBody: HTML email body content
- customerEmail: Recipient email address

### Optional Metadata Fields
- emailPreview: Preview text for inbox
- emailCc: CC recipients (array)
- emailBcc: BCC recipients (array)

### Example: See 'product_recommendation_email' predefined workflow

2. Update Workflow Agent Instructions

File: services/platform/convex/lib/create_workflow_agent.ts

Add section to system prompt:

## SENDING EMAILS FROM WORKFLOWS

Workflows DO NOT have a direct "send_email" action. Instead, use the
conversation + approval pattern:

1. Create conversation with email content in metadata (channel: 'email', direction: 'outbound')
2. Create approval linked to the conversation (resourceType: 'conversations')
3. System auto-sends email when approval is reviewed

IMPORTANT: Always check the 'product_recommendation_email' predefined workflow
as a reference for email sending patterns.

3. Update Conversation Action Documentation

File: services/platform/convex/workflow/actions/conversation/conversation_action.ts

Enhance the description:

description: `Execute conversation-specific operations.

For EMAIL WORKFLOWS:
When creating outbound email conversations, include these metadata fields:
- emailSubject: Subject line
- emailBody: HTML body content
- customerEmail: Recipient address
Then create an approval (resourceType: 'conversations') to trigger sending.
`

4. Update Chat Agent Instructions (Optional)

File: services/platform/convex/lib/create_chat_agent.ts

Add knowledge about email workflows:

When users ask about sending emails via workflows:
- Explain the conversation + approval pattern
- Reference the product_recommendation_email predefined workflow
- Email sending requires human approval by default

Implementation Steps

1. Edit workflow_syntax_compact.ts:

   • Add "EMAIL SENDING PATTERN" section with full documentation
   • Include metadata field reference
   • Reference product_recommendation_email example

2. Edit create_workflow_agent.ts:

   • Add brief email workflow summary in system prompt
   • Direct agent to use workflow_examples tool for email patterns

3. Edit conversation_action.ts:

   • Enhance description with email metadata documentation

4. (Optional) Edit create_chat_agent.ts:

   • Add email workflow guidance

Expected Outcome

After these changes, when a user asks:

"Create a workflow that sends a welcome email to new customers"

The workflow agent will:

1. Know to use conversation + approval pattern (not look for send_email)
2. Create conversation with proper email metadata fields
3. Create approval linked to conversation
4. Explain that email sends after approval

Key Files Reference

• services/platform/convex/workflow/workflow_syntax_compact.ts - Main documentation
• services/platform/convex/lib/create_workflow_agent.ts - Agent instructions
• services/platform/convex/workflow/actions/conversation/conversation_action.ts - Action docs
• services/platform/convex/predefined_workflows/product_recommendation_email.ts - Working example