manage-async-jobs

name	manage-async-jobs
description	Using the /events/ directory to schedule one-shot (at) or periodic (cron) jobs that fire asynchronously, possibly in a thread

Events

Create JSON files in /events/, use unique filenames.

One-shot (fire once at a specific ISO 8601 time)

{"type": "one-shot", "text": "Remind to go to sleep early", "at": "2026-02-26T23:00:00+01:00"}

Past files auto-delete.

Periodic (cron schedule)

{"type": "periodic", "text": "Check inbox", "schedule": "0 9 * * 1-5", "timezone": "Europe/Prague"}

The file persists until you delete it.

Thread context

When creating an event inside a thread, threadId is automatically set to the current thread — no manual action needed. The event will fire back into the same thread. To override, include an explicit "threadId" in the JSON.

Mode selection

The event text is processed like a normal message by you as an AI agent. Prefix with a trigger such as !s/!a/!u to force a particular command mode.

Guidelines

• Cron vs. heartbeat: Use cron for specific jobs with clear frequency. Use heartbeat for jobs to be done generally "frequently / continuously".
• Consolidate related checks into a single periodic event rather than many separate ones.
• Explicitly instruct cron jobs when & how should they say something - the job's agent will be advised to stay silent by default.
• Keep number and frequency of events reasonable - each firing is a full agent invocation.