action-creator

# Action Creator

Creates TypeScript action template files that define reusable, user-specific operations users can execute with one click in the chat interface.

## When to Use This Skill

Use this skill when the user wants to:
- Create reusable actions for their specific workflows ("I often need to send payment reminders to ACME Corp")
- Set up one-click operations for their vendors/customers ("Forward bugs to engineering team")
- Automate repetitive email tasks with their specific context ("Archive newsletters from TechCrunch/Morning Brew")
- Build personalized email management tools for their business processes

**Key difference from listeners**: Actions are **user-triggered** (clicked in chat), while listeners are **event-triggered** (automatic).

## How Actions Work

Actions are TypeScript files in `agent/custom_scripts/actions/` that:
1. Export a `config` object defining the template metadata and parameter schema
2. Export a `handler` function that executes the operation with given parameters
3. Use `ActionContext` methods to perform operations (email API, send emails, call AI, etc.)

The agent creates **action instances** during conversation by providing specific parameters to these templates, which appear as clickable buttons in the chat.

## Creating an Action Template

### 1. Understand User-Specific Workflow

Parse the user's request to identify:
- **User context**: Who are their specific vendors/customers/teams?
- **Operation**: What specific action do they need? (send to ACME Corp, forward to engineering team, etc.)
- **Parameters**: What varies per execution? (invoice number, priority level, days old)
- **Frequency**: How often will they use this?

### 2. Write the Action Template File

Create a file in `agent/custom_scripts/actions/` with this structure:

```typescript
import type { ActionTemplate, ActionContext, ActionResult } from "../types";

export const config: ActionTemplate = {
  id: "unique_action_id",                    // kebab-case, user-specific
  name: "Human Readable Name",                // For UI display
  description: "What this action does",       // Explain the operation
  icon: "📨",                                 // Optional emoji icon
  parameterSchema: {
    type: "object",
    properties: {
      paramName: {
        type: "string",                      // or "number", "boolean"
        description: "Parameter description",
        enum: ["option1", "option2"],        // Optional: restrict values
        default: "defaultValue"              // Optional: default value
      }
    },
    required: ["paramName"]                  // List required parameters
  }
};

export async function handler(
  params: Record<string, any>,
  context: ActionContext
): Promise<ActionResult> {
  const { paramName } = params;

  context.log(`Starting action: ${config.name}`);

  try {
    // 1. Perform operations using context methods
    // 2. Use AI for intelligent processing if needed
    // 3. Update emails, send emails, etc.

    context.notify("Action completed successfully", {
      type: "success",
      priority: "normal"
    });

    return {
      success: true,
      message: "Action completed successfully",
      data: { /* optional structured data */ },
      refreshInbox: true  // Optional: refresh inbox after action
    };
  } catch (error: any) {
    context.log(`Action failed: ${error}`, "error");
    return {
      success: false,
      message: `Failed: ${error.message}`
    };
  }
}
```

### 3. File Naming Convention

Use kebab-case that reflects the **user-specific** operation:
- `send-payment-reminder-to-acme.ts` (not `send-email.ts`)
- `forward-bugs-to-engineering.ts` (not `forward-email.ts`)
- `archive-newsletters-from-techcrunch.ts` (not `archive-emails.ts`)
- `summarize-weekly-updates-from-ceo.ts` (not `summarize-emails.ts`)

**Important**: Templates should be specific to the user's actual workflows, vendors, teams, and processes.

### 4. Available Context Methods

The `ActionContext` provides these capabilities:

```typescript
// Email API operations
const emails = await context.emailAPI.getInbox({ limit: 30, includeRead: false });
const results = await context.emailAPI.searchEmails({ from: "sender@example.com" });
const results = await context.emailAPI.searchWithGmailQuery("from:sender after:2024/01/01");
const emails = await context.emailAPI.getEmailsByIds(["id1", "id2"]);
const email = await context.emailAPI.getEmailById("email-id");

// Direct email operations
await context.archiveEmail(emailId);
await context.starEmail(emailId);
await context.unstarEmail(emailId);
await context.markAsRead(emailId);
await context.markAsUnread(emailId);
await context.addLabel(emailId, "label-name");
await context.removeLabel(emailId, "label-name");

// Send emails
const result = await context.sendEmail({
  to: "recipient@example.com",
  subject: "Email subject",
  body: "Email body content",
  cc: "cc@example.com",           // Optional
  bcc: "bcc@example.com",          // Optional
  replyTo: "reply@example.com"     // Optional
});

// AI-powered processing
const analysis = await context.callAgent<ResultType>({
  prompt: "Analyze this email and extract key info...",
  systemPrompt: "You are an expert at...",  // Optional
  tools: ["Read", "WebSearch"],              // Optional
  maxTokens: 2000                            // Optional
});

// Session messaging (inject into chat)
context.addUserMessage("User said this");
context.addAssistantMessage("Assistant responds");
context.addSystemMessage("System notification");

// Notifications
context.notify("Operation completed", {
  priority: "high" | "normal" | "low",
  type: "info" | "success" | "warning" | "error"
});

// External API access
const response = await context.fetch("https://api.example.com/data");
const data = await response.json();

// Logging (visible in server logs)
context.log("Info message", "info");
context.log("Warning message", "warn");
context.log("Error message", "error");
```

## Acti