# suruf-scheduler

> Schedule and manage automated cron jobs on the Suruf platform. Create recurring tasks that run prompts on a schedule and post results to channels. Use when the user mentions scheduling, cron jobs, automated tasks, recurring jobs, or timed execution.

- Author: a.mor
- Repository: alimrb/suruf-platform-repo
- Version: 20260208142121
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-08
- Source: https://github.com/alimrb/suruf-platform-repo
- Web: https://mule.run/skillshub/@@alimrb/suruf-platform-repo~suruf-scheduler:20260208142121

---

---
name: suruf-scheduler
description: Schedule and manage automated cron jobs on the Suruf platform. Create recurring tasks that run prompts on a schedule and post results to channels. Use when the user mentions scheduling, cron jobs, automated tasks, recurring jobs, or timed execution.
---

# Scheduler Integration

Schedule automated tasks that run on a recurring basis and post results to your channel.

## Resources

| Document | Description |
|----------|-------------|
| [examples.md](examples.md) | Real-world use cases and scenarios |
| [reference.md](reference.md) | Complete API reference and tool schemas |
| [templates/job-templates.md](templates/job-templates.md) | Pre-configured job templates |
| [scripts/scripts.md](scripts/scripts.md) | Bash scripts and SQL queries |
| [assets/architecture.md](assets/architecture.md) | System architecture diagram |

## Quick Start

1. Show config form: `suruf_ui_cron_config`
2. Or create programmatically: `cron_create_job` with name, schedule, prompt
3. List all jobs: `suruf_ui_cron_list` or `cron_list_jobs`
4. Manage jobs: pause, resume, delete, or run immediately

## Architecture

- **Port**: 4000
- **MCP Server**: `suruf-ui` in settings.json
- **Code**: `extensions/mcp-apps/src/apps/scheduler/`
- **Worker**: `server/src/workers/scheduler-worker.ts`
- **Database**: `scheduled_jobs` table

## MCP Tools

### UI Tools

| Tool | Description |
|------|-------------|
| `suruf_ui_cron_config` | Show job configuration form. Pass `jobId` to edit existing job. |
| `suruf_ui_cron_list` | Show interactive list of scheduled jobs with management actions. |

### Data Tools

| Tool | Description |
|------|-------------|
| `cron_create_job` | Create a new scheduled job |
| `cron_list_jobs` | List all jobs (filter by userId, channelId, status) |
| `cron_get_job` | Get full details of a specific job |
| `cron_update_job` | Update job name, schedule, prompt, or MCP apps |
| `cron_delete_job` | Permanently delete a job |
| `cron_pause_job` | Pause job execution (keeps schedule) |
| `cron_resume_job` | Resume a paused job |
| `cron_run_now` | Execute job immediately (doesn't affect schedule) |

## Schedule Types

### Interval
Run every N hours. Simple for common use cases.

```
intervalHours: 6  → "0 */6 * * *" (every 6 hours)
intervalHours: 24 → "0 0 * * *" (daily at midnight)
intervalHours: 0.5 → "*/30 * * * *" (every 30 minutes)
```

### Cron Expression
Full cron syntax for precise scheduling.

```
┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sun-Sat)
│ │ │ │ │
* * * * *
```

**Common examples:**
- `0 9 * * *` — Every day at 9:00 AM
- `0 9 * * 1` — Every Monday at 9:00 AM
- `0 */6 * * *` — Every 6 hours
- `0 0 1 * *` — First of every month at midnight
- `30 8 * * 1-5` — Weekdays at 8:30 AM

### One-Time
Run once at a specific time (ISO 8601 timestamp).

```
scheduledAt: "2024-12-25T09:00:00Z"
```

## Job Payload

When creating a job, the payload stores:

```typescript
{
  userId: string;       // Job owner
  channelId: string;    // Where results are posted
  prompt: string;       // Task to execute
  mcpApps: string[];    // MCP servers to use
  agentId?: string;     // Specific agent (optional)
}
```

## Available MCP Apps

Jobs can use these MCP apps:

| App | Description |
|-----|-------------|
| `gmail` | Read, search, and manage emails |
| `google-calendar` | Access calendar events |
| `mcp-searxng` | Web search |
| `postgres` | Database queries |
| `youtube_transcript` | Video transcripts |
| `suruf-ui` | All UI tools (weather, charts, maps, etc.) |
| `erpnext` | ERP operations |

## Job Execution

The scheduler worker:
1. Polls every 30 seconds for due jobs
2. Creates a system message in the channel
3. Invokes the agent with the job's prompt
4. Posts the agent's response to the channel
5. Updates job statistics (runCount, lastRunAt, nextRunAt)
6. Handles failures with retry logic (max 3 retries)

## Limits

- **Max jobs per user**: 50
- **Execution timeout**: 5 minutes
- **Minimum interval**: 30 minutes (0.5 hours)
- **Max prompt length**: Reasonable (no hard limit)

## Status Values

| Status | Description |
|--------|-------------|
| `active` | Job is running on schedule |
| `paused` | Job is paused (won't execute) |
| `completed` | One-time job finished |
| `failed` | Job disabled after max retries |

## Examples

### Create a daily email digest

```
Use cron_create_job with:
- name: "Daily Email Digest"
- scheduleType: "cron"
- cronExpression: "0 9 * * *"
- prompt: "Summarize my unread Gmail messages from the last 24 hours. List any action items."
- mcpApps: ["gmail"]
```

### Create a weather alert

```
Use cron_create_job with:
- name: "Morning Weather"
- scheduleType: "interval"
- intervalHours: 24
- prompt: "Get the weather forecast for San Francisco and highlight any rain or extreme temperatures."
- mcpApps: ["suruf-ui"]
```

### Schedule a weekly report

```
Use cron_create_job with:
- name: "Weekly Calendar Summary"
- scheduleType: "cron"
- cronExpression: "0 17 * * 5" (Friday 5pm)
- prompt: "Summarize my calendar events for this week and list next week's upcoming meetings."
- mcpApps: ["google-calendar"]
```

## User Interaction: Collect Details via Forms

**MANDATORY:** When the user asks to create a scheduled job without providing all parameters, use `suruf_ui_form_generator` to collect them BEFORE creating.

**Example:** "Schedule a daily task" → form: job name (text, required), task prompt (textarea, required), schedule type (radio: interval/cron/once), interval or cron expression, MCP apps to enable (multiselect), channel (select).

See `suruf/FORM-INTERACTION.md` for the full pattern.