Scheduled Tasks

Overview

Scheduled Tasks let any authenticated user schedule a natural-language prompt to run on a cron. Each tick invokes the assistant agent as that user, records the run, and emits the next scheduled event. The runtime is Inngest via @mastra/inngest; there is no Cloudflare cron or DB polling.

Tasks are authored as Mastra workflows (runScheduledTaskWorkflow) so future multi-step flows — "fetch → compose → approve → act" — can be added without changing the scheduling machinery.

How It Works

1. User creates a task via POST /scheduled-tasks. The API validates the cron expression, computes nextRunAt, and emits a future-dated Inngest event: scheduled-task/tick with ts: nextRunAt and data: { taskId }.
2. Inngest durably holds the event until fire time.
3. The Mastra dispatcher (runScheduledTaskDispatcher) receives the event, loads the task, mints a short-TTL scheduler JWT with the creator's snapshot role, invokes the workflow, and records the run.
4. The dispatcher computes the next fire time, emits a new future-dated scheduled-task/tick, and updates nextRunAt.
5. On disable or delete the chain self-terminates — the next tick sees the task missing or enabled = false and no-ops.

This "self-perpetuating scheduled event" pattern lets Inngest handle arbitrary per-user cron expressions without registering dynamic cron functions.

Plan Gating

Scheduled tasks are gated by the plan features in packages/shared/src/plans.ts:

Disabled tasks do not count against the quota. The API enforces on create and on enable (POST /scheduled-tasks, PATCH /:id). The web UI shows an upsell card when the feature is off and disables the "Add" button when the org is at quota.

Role Behavior

Execution runs as the task creator, not as a service principal. The dispatcher mints an HS256 JWT with:

• sub: the creator's authUserId
• organizationId: the org the task was created in
• role: a snapshot of the creator's org role at task creation time (scheduled_tasks.auth_user_role)
• iss: cf-scheduler, TTL 10 min

Tool calls from the scheduled run authenticate with these claims, so role gating at tool level is unchanged. A non-admin who schedules an admin-only tool call gets a permission error on each tick; the chain continues.

The snapshot is frozen at creation time. If you need live role lookup, migrate to the Better Auth admin plugin (deferred — out of scope for v1).

Configuration

Environment Variables

scripts/conductor/deploy.sh pushes all three secrets to the right Workers on deploy. SCHEDULER_JWT_SECRET is auto-generated on first deploy if not present in scripts/env/.env.dev-secrets.

Inngest App Setup

One-time setup at app.inngest.com:

1. Create a new Inngest app.
2. Grab the Event Key (Manage → Event Keys) and the Signing Key (Manage → Signing Key). Put them in scripts/env/.env.dev-secrets as INNGEST_EVENT_KEY and INNGEST_SIGNING_KEY, and in the GitHub repo secrets for CI environments.
3. Deploy. scripts/conductor/deploy.sh and .github/workflows/deploy-environment.yml both PUT to /inngest after the Mastra worker deploys, so Inngest auto-discovers the dispatcher and workflow functions. No manual sync in the dashboard.

Because the sync runs on every deploy, each conductor workspace and each development/preview push keeps its function list up to date without extra steps.

Local Development

Run the Inngest dev server pointed at the Mastra worker — no Inngest account needed:

npx inngest-cli@latest dev -u http://localhost:4111/inngest

The dashboard at localhost:8288 shows registered functions, pending events, and run history. Leave INNGEST_EVENT_KEY and INNGEST_SIGNING_KEY blank in .dev.vars / .env — the dev server accepts unsigned requests.

Still set SCHEDULER_JWT_SECRET (identical value in apps/api/.dev.vars and apps/mastra/.env) so service-to-service calls and tool JWTs verify.

Database

Two tables in the API business database:

• scheduled_tasks — one row per task. Holds the cron, prompt, enabled flag, next_run_at, and the auth_user_role snapshot.
• scheduled_task_runs — one row per run. Status, response, error, Mastra thread id.

Migrations: migrations/0013_add_scheduled_tasks.sql and migrations/0014_scheduled_tasks_auth_user_role.sql.

API Surface

User-Facing (JWT-authenticated)

Internal (scheduler JWT only)

The dispatcher calls these under /admin-internal/scheduled-tasks/* using a minimal sub: "scheduler" JWT. They are not exposed to end users.

Troubleshooting

Tasks don't fire. Check the Inngest dashboard for pending scheduled-task/tick events. If none, the initial inngest.send() from the API didn't go through — verify INNGEST_EVENT_KEY on the API Worker.

Function registration fails. Inngest cannot reach the Mastra worker. Verify the registered URL is correct and /inngest returns 200 on GET.

Tool calls from scheduled runs return 401/403. The scheduler JWT's role claim is the snapshot taken at task creation. If the user's role in the org has changed since, create a new task — the snapshot doesn't auto-sync.

Chain dies unexpectedly. Check the Mastra worker logs for the tick event — if the task row was deleted or flipped to enabled = false, the dispatcher logs "scheduled-task/tick: skipping" and intentionally doesn't re-emit.