Scheduled Tasks

How It Works

Teleton uses Telegram's native scheduled messages to implement task scheduling. There is no cron daemon or config-file scheduler. The flow is:

1. A task is created (via /task command or the agent's telegram_create_scheduled_task tool).
2. A [TASK:uuid] message is scheduled in your Saved Messages at the target time.
3. When Telegram delivers the message, the agent intercepts it and executes the task.
4. The agent receives full context (description, payload, parent results) and runs with all available tools.
5. The task is marked as done or failed in the database, and any dependent tasks are triggered or cancelled.

The /task Command

Admins can create tasks directly from Telegram:

/task Check TON price and alert me if it's above $5

/task In 2 hours, send a summary of today's wallet transactions

/task Review trading performance this week

The /task command is an agent directive — it sends the description to the agent, which then decides the appropriate schedule time and payload type and calls telegram_create_scheduled_task internally. You describe what you want in natural language; the agent does the scheduling.

telegram_create_scheduled_task Tool

The agent (and plugins) can create tasks programmatically using this tool. It accepts the following parameters:

Payload Types

The payload field controls how the task is executed. There are three modes:

1. Simple Reminder (no payload)

When no payload is provided, the agent receives a reminder notification and decides what to do.

{
  "description": "Review trading performance this week",
  "scheduleDate": "2025-01-05T18:00:00Z",
  "reason": "Weekly review"
}

2. Tool Call (auto-executed)

A specific tool is called automatically, and the result is fed to the agent for analysis and decision-making.

{
  "description": "Check TON price",
  "scheduleDate": "2025-01-01T10:00:00Z",
  "payload": "{\"type\":\"tool_call\",\"tool\":\"ton_get_price\",\"params\":{},\"condition\":\"price > 5\"}",
  "reason": "Monitor for trading opportunity"
}

The condition field is optional and passed to the agent as context to guide its decision after seeing the tool result.

3. Agent Task (multi-step)

The agent receives detailed instructions and executes them step-by-step using the full agentic loop.

{
  "description": "Trade if conditions are right",
  "scheduleDate": "2025-01-01T15:00:00Z",
  "payload": "{\"type\":\"agent_task\",\"instructions\":\"1. Check TON price\\n2. If above $5, swap 50 TON to USDT\\n3. Send result to admin\",\"context\":{\"maxAmount\":50}}",
  "reason": "Automated trading strategy"
}

Task Dependencies

Tasks can depend on other tasks using the dependsOn parameter. When all parent tasks complete successfully, the dependent task is triggered automatically by sending a [TASK:uuid] message to Saved Messages.

// Task A: check the price
{
  "description": "Fetch current TON price",
  "scheduleDate": "2025-01-01T10:00:00Z",
  "payload": "{\"type\":\"tool_call\",\"tool\":\"ton_get_price\",\"params\":{}}"
}
// Returns taskId: "aaa-111"

// Task B: runs after Task A completes
{
  "description": "Analyze price and decide on trade",
  "dependsOn": ["aaa-111"],
  "payload": "{\"type\":\"agent_task\",\"instructions\":\"Review the parent task price result. If TON > $5, swap 50 TON to USDT.\"}"
}

When Task B executes, the agent receives the results from Task A as context in a PARENT TASKS COMPLETED section of the prompt.

Failure Cascade

If a parent task fails, all dependent tasks are cancelled by default. You can override this with skipOnParentFailure: false in the payload — this means the dependent task will still run even if its parent failed.

{
  "description": "Send daily summary (always)",
  "dependsOn": ["aaa-111"],
  "payload": "{\"type\":\"agent_task\",\"instructions\":\"Send a summary report.\",\"skipOnParentFailure\":false}"
}

Cycle Detection

The system uses BFS to detect circular dependencies. Attempting to create a cycle throws an error.

Task Lifecycle

Each task progresses through these statuses:

Storage

Tasks are stored in the SQLite database in two tables:

• tasks : stores task metadata (id, description, status, priority, payload, reason, timestamps, scheduled_message_id)
• task_dependencies : stores parent-child relationships between tasks (task_id, depends_on_task_id)

No configuration file is needed. Tasks are created at runtime through the tool or admin command.

Security Limits

• Each parent task can have at most MAX_DEPENDENTS_PER_TASK dependents to prevent DoS via mass dependency chains.
• Scheduled messages must be in the future.
• Payloads are validated: tool_call requires a tool field, agent_task requires instructions (min 5 characters).
• Task prompts are truncated at MAX_TOTAL_PROMPT_CHARS to prevent context overflow.
• Dependent tasks are triggered with a delay between each to avoid Telegram rate limits.