Scheduled Tasks

Overview

Scheduled tasks (Cron Jobs) allow you to configure agents to periodically and automatically execute repetitive work without manual intervention. Use cases include:

• Daily code reviews
• Weekly security scans
• Monthly dependency update checks
• Scheduled log analysis and report generation

Scheduled tasks are created and managed by the agent itself through MCP tools, not by Sink directly. Agents can set up, modify, or cancel scheduled tasks during task execution.

Understanding Scheduled Tasks

Relationship Between Tasks and Cron Jobs

• Task: A single agent work session (e.g., one code review)
• Cron Job: A definition for repeated task execution (e.g., run code review daily)

Each execution of a Cron Job corresponds to an independent task. The system automatically creates a new task at the scheduled time and launches the agent with the same profile.

Cron Expressions

Scheduled tasks use the standard Cron expression format (5 fields):

┌───────────── Minute (0 - 59)
│ ┌───────────── Hour (0 - 23)
│ │ ┌───────────── Day (1 - 31)
│ │ │ ┌───────────── Month (1 - 12)
│ │ │ │ ┌───────────── Weekday (0 - 6, 0 = Sunday)
│ │ │ │ │
│ │ │ │ │
* * * * *

Cron Expression Examples

Wildcard Symbols

Creating Scheduled Tasks

Via Agent

Agents can create scheduled tasks through MCP tools during task execution:

Please create a scheduled task for me:
- Name: "Daily Code Review"
- Cron expression: 0 2 * * * (every day at 2 AM)
- Description: Automatically review code changes daily

The agent will:

1. Validate the cron expression
2. Register the scheduled task with the system
3. Automatically trigger at the specified time

Schedule Parameters

Sink provides two cron modes, each with different parameters:

Notify mode (cron_set)

Sends a message to the current task at scheduled times.

• scheduleId: A unique identifier for the schedule. Allowed characters: alphanumeric, _, and -. Maximum 64 characters. Example: daily-reminder
• Cron expression: Standard 5-field cron expression (see above)
• message: The text message to deliver to this task’s inbox on each tick
• enabled (optional): Whether to enable the schedule immediately. Defaults to true

Spawn mode (cron_spawn)

Creates a new subtask at scheduled times.

• scheduleId: A unique identifier for the schedule. Same naming rules as notify mode
• Cron expression: Standard 5-field cron expression (see above). Minimum interval: 5 minutes
• prompt: A description of what the spawned subtask should accomplish on each tick
• enabled (optional): Whether to enable the schedule immediately. Defaults to true
• concurrency (optional): Controls behavior when a previous invocation is still running:
  • serial (default) — Skip the tick if the previous child task is still active
  • parallel — Always spawn a new task on every tick
• profileId (optional): Which profile to use for the spawned subtask
• executionMode (optional): individual or team for the spawned subtask
• managed (optional): Whether the spawned subtask operates in managed mode (defaults to false)
• configOverrides (optional): Per-config-key value overrides for the spawned subtask’s profile

Viewing Created Scheduled Tasks

On the task details page, in the “Scheduled Tasks” tab, you can see:

• Task name: The identifier for the scheduled task
• Cron expression: The execution schedule
• Created at: When it was created
• Last execution: When it last ran
• Next execution: Expected time for the next run
• Status: Enabled/disabled

Managing Scheduled Tasks

Pause a Scheduled Task

If you need to temporarily stop a scheduled task, you can disable it in the Web UI:

1. Open the task containing the scheduled task
2. Find the “Scheduled Tasks” tab
3. Select the task you want to disable
4. Click the “Disable” button

Once disabled, it won’t execute automatically, but the configuration is preserved.

Re-enable a Scheduled Task

1. In the “Scheduled Tasks” tab, select the disabled task
2. Click the “Enable” button

The task will resume execution according to its original schedule.

Modify a Scheduled Task

The system does not support directly modifying scheduled task parameters. To change the schedule or message content, you must delete and recreate the task:

1. Ask the agent to delete the existing scheduled task (cron_remove)
2. Ask the agent to recreate it with new parameters (cron_set or cron_spawn)

For example:

Delete the scheduled task "Daily Code Review" and create a new one:
- New cron expression: 0 10 * * 1-5 (change to 10 AM on weekdays)

Delete a Scheduled Task

If you no longer need a scheduled task, you can delete it:

1. In the “Scheduled Tasks” tab, select the task you want to delete
2. Click the “Delete” button
3. Confirm the deletion

Once deleted, the scheduled task will no longer execute.

Scheduled Task Execution

Automatic Execution Flow

When a scheduled task is triggered:

1. Create New Task
   • The system automatically creates a new task instance
   • The task uses the same profile and configuration as the original task
   • The task description will include an “auto-executed” marker
2. Launch Agent
   • The agent launches according to the system prompt defined in the profile
   • The agent automatically loads the same instruction files and configuration
3. Perform Work
   • The agent executes the assigned work
   • You can still monitor progress in real-time
   • Agents still ask for permissions when needed
4. Complete Task
   • The agent completes the work and generates a report
   • The task enters its final state

View Execution History

Click the “History” option for a scheduled task to see all past execution records:

• Execution time
• Task ID
• Execution status (success/failure/in progress)
• Duration
• Generated report

Common Scenarios

Scenario 1: Daily Code Review

Scheduled task configuration:
- Name: Daily Code Review
- Profile: Code Reviewer
- Cron: 0 2 * * *
- Description: Automatically review new code daily at 2 AM, checking for quality and correctness issues

Steps:
1. Agent starts automatically
2. Read code changes from the last 24 hours
3. Perform security analysis
4. Generate audit report
5. Send notification or email

Scenario 2: Weekly Dependency Check

Scheduled task configuration:
- Name: Weekly Dependency Audit
- Profile: Dependency Analyzer
- Cron: 0 0 * * 0
- Description: Check dependency updates and security patches every Sunday at midnight

Steps:
1. Scan all dependency versions
2. Check known vulnerability database
3. Identify available security updates
4. Generate upgrade recommendation report

Scenario 3: Monthly Report Generation

Scheduled task configuration:
- Name: Monthly Summary
- Profile: Report Generator
- Cron: 0 9 1 * *
- Description: Generate summary report at 9 AM on the 1st of every month

Steps:
1. Collect data and metrics from the previous month
2. Analyze trends and changes
3. Generate detailed report
4. Send to relevant teams

Best Practices for Scheduled Tasks

1. Set Reasonable Execution Times

• Avoid peak hours: Run during non-business hours to avoid impacting other work
• Consider timezone: Clarify which timezone the cron time executes in
• Avoid conflicts: Don’t let multiple scheduled tasks run at the same time (unless necessary)

2. Set Up Monitoring and Alerts

• Regularly check the “Execution History”
• Investigate failures promptly
• Consider having the agent send notifications on failure

3. Regular Review

• Check your scheduled task list monthly and delete ones you no longer need
• Adjust execution times based on actual needs
• Verify the quality of agent execution

4. Resource Considerations

• The number of concurrently executing scheduled tasks is limited by agentLifecycle.maxConcurrent in settings.json
• Avoid scheduled tasks consuming excessive resources
• Monitor system resource usage
• Each task can have at most 32 scheduled entries (MAX_CRON_SCHEDULES)
• The minimum interval for spawn schedules is 5 minutes (denser expressions trigger at most once every 5 minutes)

5. Logging and Reporting

• Have the agent generate detailed logs for each execution
• Retain execution history for later review
• Periodically export reports for archival

Troubleshooting

Scheduled Task Not Executing On Time

Possible causes:

• Incorrect cron expression
• System is in maintenance or down
• Expression interval is shorter than 5 minutes (spawn schedules are rate-limited to a minimum interval of 5 minutes; denser expressions will fire at most once every 5 minutes)
• Concurrent slots are full, new tasks are queued

Checking steps:

1. Verify the cron expression syntax (use an online cron tool to check)
2. Check if the system is online
3. Check if the expression interval is at least 5 minutes (spawn rate limit)
4. Check if the number of “concurrent tasks” has reached its limit

Scheduled Task Execution Failed

Possible causes:

• Agent encountered an error
• Required data or tools are unavailable
• Profile configuration is not suitable for periodic execution

Investigation steps:

1. View the failed task in “Execution History”
2. Read the detailed logs and error messages of the task
3. Manually run a test task to see if you can reproduce the problem
4. After modifying the profile or instructions, edit the scheduled task and re-enable it

Scheduled Task Created Successfully But Not Displaying

Possible causes:

• Browser cache
• Scheduled task was created in another tab
• Permission restrictions

Solutions:

1. Refresh the page (F5)
2. Check if the task exists in other open tabs
3. Verify you have permission to view the task’s scheduled tasks

Next Steps

• Managing Profiles — Select appropriate profiles for scheduled tasks
• Configuring Gateway — Adjust system concurrency settings
• Quick Start — Create your first task and learn the workflow