feat: Scheduled Jobs

[angelplusultra]

Pull Request Type

• ✨ feat (New feature)

Relevant Issues

resolves #5349

Description

Adds Scheduled Jobs — recurring AI tasks that run prompts with optional agent tools on a cron schedule (single-user mode only).

Users can create jobs with a name, prompt, cron schedule, and optional tool selection from all configured agent skills (built-in, MCP servers, agent flows, imported plugins). Jobs run automatically via cron timers, and each execution captures a full trace — agent thinking, tool calls with their results, and the final response.

Key capabilities:

• Create, edit, delete, enable/disable jobs with cron scheduling
• Per-job tool selection from all configured agent skills
• Full execution trace capture (thinking, tool calls + results, response, metrics)
• Run history (last 50 runs) with read/unread tracking
• Run detail view with collapsible trace inspection and syntax-highlighted tool call results
• "Run Now" button for immediate execution (works regardless of enabled state)
• "Continue in Thread" to fork a completed run into a workspace thread for follow-up conversation
• Uses web push notifications (VAPID keys, service worker) to notify users when a job completes
• Configurable concurrency limit (SCHEDULED_JOB_MAX_CONCURRENT, default 1) and timeout (SCHEDULED_JOB_TIMEOUT_MS, default 5 min)
• Cold startup recovery (orphaned runs marked failed, stale schedules recomputed)

Architecture:

• Cron timers are managed in-process via later.setInterval rather than Bree's built-in scheduling because Bree tightly couples scheduling with worker spawning — when a Bree cron fires it directly spawns a child process with no way to intercept. By owning the timers we can route executions through a p-queue instance for concurrency control, deduplication, and priority ordering before spawning workers via runJob().
• Worker uses EphemeralAgentHandler — same proven agent runtime as the Telegram bot
• New toolCallResult event on AIbitat for capturing tool outputs in the execution trace
• New toolOverrides param on EphemeralAgentHandler.createAIbitat() for per-job tool restriction
• Uses the system-level LLM provider (falls through workspace agent → workspace chat → system provider resolution chain, since the auto-created "Scheduled Jobs" workspace has no provider overrides)

Route protection:

• New SingleUserRoute wrapper in PrivateRoute/index.jsx — redirects to home if in multi-user mode, similar to how AdminRoute and ManagerRoute handle RBAC. This keeps the single-user-only restriction at the route level via main.jsx so individual page components don't need to duplicate auth/redirect logic. Server-side enforcement is handled by the existing isSingleUserMode middleware on all scheduled job endpoints.

Frontend structure:

• ScheduledJobs/index.jsx — job list with CRUD, toggle, trigger
• ScheduledJobs/RunHistoryPage.jsx — run history table for a job
• ScheduledJobs/RunDetailPage.jsx — full run detail with trace viewer
• ScheduledJobs/NewJobModal.jsx — create/edit modal
• ScheduledJobs/utils/cron.js — shared cron presets and cronToHuman helper

Additional Information

• Named "Scheduled Jobs" rather than "Background Jobs" (as in the PRD) to avoid confusion with the existing BackgroundService/Bree infrastructure
• Single-user mode only for v1. No multi-user, no retry mechanism
• Run history is capped at 50 most recent runs per job. Pagination can be added later if needed.

Demo of Job Creation, Job Run Inspection and Forwarding Job Run to New Thread

output.mp4

Demo of Job Completion Push Notification

trimmed_demo.mp4

Development

This PR contains new DB migrations, make sure to run yarn prisma migrate dev before testing the feature.

Developer Validations

• I ran yarn lint from the root of the repo & committed changes
• Relevant documentation has been updated (if applicable)
• I have tested my code functionality
• Docker build succeeds locally