Cron Management

Critical Rules

1. •

   sessionTarget/payload pairing is mandatory:

   • •sessionTarget: "main" requires payload.kind: "systemEvent"
   • •sessionTarget: "isolated" requires payload.kind: "agentTurn"
   • •Mismatches cause silent failures
2. •

   Always verify after creating: After cron add, immediately run cron list to confirm the job exists, is enabled, and nextRunAtMs is in the future.

3. •

   Always use wakeMode: "now" for time-sensitive jobs. Default "next-heartbeat" waits for the next heartbeat cycle which may be minutes away.

4. •

   Timezone matters: Always set tz for cron expressions. Without it, the Gateway host's local timezone is used (likely UTC on servers).

Decision Tree: Which Job Type?

User wants scheduled task
├── Simple reminder/nudge to self (main agent context needed)?
│   → sessionTarget: "main", payload: systemEvent
│   → The text becomes a system event processed during heartbeat
│   → Agent sees it with full main conversation context
│
└── Task requiring agent work (generate, analyze, fetch, summarize)?
    → sessionTarget: "isolated", payload: agentTurn
    → Runs in dedicated session cron:<jobId>
    → Summary posted back to main session
    → Can deliver output to WhatsApp/Telegram/Slack/Discord

Schedule Types

One-shot jobs (at): After successful run, they auto-disable. Use deleteAfterRun: true to auto-delete instead.

Creating Jobs via the cron Tool

Use action: "add" with a job object. See references/tool-schemas.md for complete schemas and examples.

Minimal one-shot reminder (main session)

{
  "action": "add",
  "job": {
    "name": "Reminder: <descriptive name>",
    "schedule": { "kind": "at", "at": "20m" },
    "sessionTarget": "main",
    "wakeMode": "now",
    "payload": { "kind": "systemEvent", "text": "Reminder: <what to do>" },
    "deleteAfterRun": true
  }
}

Recurring isolated job with delivery

{
  "action": "add",
  "job": {
    "name": "Morning brief",
    "schedule": { "kind": "cron", "expr": "0 10 * * *", "tz": "America/Sao_Paulo" },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "payload": {
      "kind": "agentTurn",
      "message": "<clear, self-contained prompt>",
      "deliver": true,
      "channel": "whatsapp",
      "to": "+5531XXXXXXXXX",
      "bestEffortDeliver": true
    },
    "isolation": { "postToMainMode": "summary" }
  }
}

Writing Effective Cron Prompts

The cron prompt runs in an isolated session with no prior conversation context. Write prompts that are:

1. •Self-contained: Include all context needed. The isolated agent has no memory of previous conversations.
2. •Specific about output: State exactly what format/length you want. Without guidance, responses can be long and get truncated during delivery.
3. •Aware of available tools: The isolated agent has access to all configured tools (web search, file read/write, workspace files, messaging, etc.). Reference them if the task requires them.
4. •Concise about delivery: If delivering to chat, mention "keep response under N words" or "respond in 2-3 short paragraphs" — long messages get truncated by channel limits (WhatsApp ~4096 chars, Telegram ~4096 chars).

Good prompt examples

"Leia o arquivo ~/workspace/tarefas.md, resuma as tarefas pendentes em no máximo 3 linhas, e envie."

"Check the calendar for today's meetings. List them as bullet points. Keep under 500 chars."

Bad prompt examples

"Summarize updates."

(No context about what updates, where to find them, or output format)

"Do the weekly report and send it to everyone."

(No specifics about report content, data sources, recipients, or format constraints)

Using contextMessages for Reminders

When creating reminders from a conversation, use contextMessages: 3-5 to attach recent conversation context to the job's text. This way, when the reminder fires, it carries enough context about what was being discussed.

{
  "action": "add",
  "contextMessages": 5,
  "job": {
    "name": "Follow up on discussion",
    "schedule": { "kind": "at", "at": "2h" },
    "sessionTarget": "main",
    "wakeMode": "now",
    "payload": { "kind": "systemEvent", "text": "Follow up: revisit the API design discussion" },
    "deleteAfterRun": true
  }
}

Post-Creation Verification Checklist

After every cron add, verify:

1. •cron list — job appears, enabled: true, nextRunAtMs is correct
2. •For recurring jobs, consider cron run <jobId> with mode: "force" to test immediately
3. •After test run, check cron runs for status: "ok" and verify the summary/output
4. •If delivering to a channel, confirm the message arrived at the target

Common Pitfalls

Managing Existing Jobs

// List all (including disabled)
{ "action": "list", "includeDisabled": true }

// Update schedule
{ "action": "update", "jobId": "<id>", "patch": { "schedule": { "kind": "every", "everyMs": 7200000 } } }

// Disable/enable
{ "action": "update", "jobId": "<id>", "patch": { "enabled": false } }

// Force run for testing
{ "action": "run", "jobId": "<id>" }

// Check run history
{ "action": "runs", "jobId": "<id>" }

// Delete
{ "action": "remove", "jobId": "<id>" }