Schedule

Use a Static Schedule Definition for cron entries deployed with the app. Use Runtime Schedules when the app creates, updates, or removes recurring work while it runs.

A Schedule Target can start an Agent Invocation, but Schedule itself runs on the server. Give an Agent schedule access only through a Schedule Capability.

Quick start

pnpm add @vite-hub/schedule

import { hubSchedule } from '@vite-hub/schedule/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [hubSchedule()],
})

import { defineSchedule } from '@vite-hub/schedule'

export default defineSchedule({
  cron: '0 8 * * *',
  async handler({ scheduledAt, waitUntil }) {
    await sendDailyReport(scheduledAt)
    waitUntil(recordDelivery())
  },
})

Public imports

Schedule Definition, Runtime Schedule, Schedule Run, and Schedule Store types are exported from @vite-hub/schedule.

Configure the Vite Integration

import { hubSchedule } from '@vite-hub/schedule/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    hubSchedule({
      runtime: {
        driver: 'process',
        prefix: 'my-app:schedule',
      },
    }),
  ],
})

Use createScheduleNitroConfig() when a Nitro integration owns config merging and needs Schedule to return Nitro-ready provider output.

The Process Runtime imports the discovered registry and runs Static Schedule Definitions alongside persisted Runtime Schedules through one driver queue. It creates the Runtime Schedule and Schedule Run stores through the default KV store configured by hubKv(), applies the Schedule prefix to both, reports errors through Nitro, and closes the driver during Nitro shutdown. It scans once per minute with one concurrent wake unless configured otherwise, and intervalMs cannot exceed the one-minute cron resolution. This setting is orthogonal to providerOutput; selecting one does not infer the other.

Provider output

Define a static schedule

Use a Static Schedule Definition when the host needs build-time Provider Output such as cron entries or provider wake configuration.

import { defineSchedule } from '@vite-hub/schedule'

export default defineSchedule({
  cron: '0 8 * * *',
  async handler(context) {
    await sendDailyReport(context.scheduledAt)
  },
})

Cron expressions use the Schedule Time Base, currently UTC. The discovered file name provides the Static Schedule Definition identity.

Schedule Definition options

ScheduleRunContext includes id, scheduledAt, waitUntil, optional attemptId, optional runId, optional Runtime Schedule id, optional Runtime Schedule target, and optional Runtime Schedule input.

Use waitUntil(promise) for consequential work that can outlive the handler body. Direct and local execution settles registered work before recording the Schedule Run result; a rejection fails the run with the same diagnostics as a handler rejection. An installed wake runtime instead retains registered work after the handler returns, reports rejection through its onError hook, and drains outstanding work when the runtime closes.

Create recurring Runtime Schedules

Runtime Schedules are cron schedules stored by ViteHub. A Runtime Schedule can target only a Runtime Schedule Target that opted into runtime reuse. Set an IANA timeZone when the cron must follow local civil time and daylight-saving changes. Omit it to use UTC.

Use defineScheduleTarget() when the handler runs only through Runtime Schedules and doesn't need its own build-time cron. These targets don't emit static provider output.

import { defineScheduleTarget } from '@vite-hub/schedule'

export default defineScheduleTarget<{ prompt: string }>({
  async handler({ input }) {
    if (input) await generateReport(input.prompt)
  },
})

defineSchedule() remains cron-required and can opt into runtime reuse with allowRuntimeSchedules:

import { defineSchedule } from '@vite-hub/schedule'

export default defineSchedule({
  allowRuntimeSchedules: true,
  cron: '0 8 * * *',
  async handler() {
    await sendDailyReport()
  },
})

Use the schedules Runtime Helper from server code.

import { schedules } from '@vite-hub/schedule/runtime'

export default defineEventHandler(async () => {
  return schedules.create({
    cron: '30 8 * * 1-5',
    id: 'weekday-report',
    input: { prompt: 'Summarize yesterday' },
    target: 'report',
    timeZone: 'Europe/Copenhagen',
  })
})

Runtime Schedule input

RuntimeScheduleUpdateInput accepts cron, target, enabled, input, and timeZone. Create stores an input snapshot. Providing input on update replaces the complete snapshot; omitting it preserves the existing value. Schedule does not merge or interpret input, and the configured store must support the value's serialization requirements. Omitting timeZone on update preserves the stored zone; set it explicitly to UTC to reset UTC evaluation.

Local cron matching follows conventional daylight-saving behavior: a local time missing during a DST gap is skipped, while both distinct instants in a repeated local time during a DST overlap run.

Runtime helper methods

One-time delayed execution is not part of the first-version Scheduling vocabulary; use a recurring cron schedule, Queue delay, or Workflow design when that matches the actual behavior.

Connect a Runtime Schedule wake driver

Host integrations use a wake driver when the host can create and remove native schedule registrations at runtime.

import { installScheduleRuntime } from '@vite-hub/schedule/runtime/driver'

const controller = await installScheduleRuntime({
  createDriver: context => hostScheduler.driver(context),
  registry: scheduleRegistry,
  runtimeScheduleStore,
  scheduleRunStore,
  staticRegistry: scheduleRegistry,
})

createDriver(context) returns a driver with reconcile(schedules). Pass staticRegistry when the driver also schedules discovered Static Schedule Definitions. Each reconciliation then receives those definitions with the complete stored Runtime Schedule snapshot, including disabled records. Installation waits for the first reconciliation.

The installed runtime processes Runtime Schedule creates, updates, and deletes one at a time. It saves each change before reconciling the wake driver. If reconciliation fails, ViteHub restores the previous record and rejects the change. Manual schedules.run() calls execute immediately and don't reconcile the driver.

When the host fires a native wake, call context.wake({ scheduleId, scheduledAt }) with the exact stored Runtime Schedule id and occurrence time. Call controller.close() during host shutdown to release process resources; closing does not delete definitions, schedules, or run history.

Use createProcessScheduleWakeDriver() from @vite-hub/schedule/runtime/process when a custom long-running host wants the same in-process wake behavior without generated Nitro wiring.

startScheduleRunner() has been removed. Existing self-hosted processes must install createProcessScheduleWakeDriver() through installScheduleRuntime() and await controller.close() during host shutdown.

Static provider output remains build-time configuration; selecting the Process Runtime also executes discovered Static Schedule Definitions without requiring provider output.

Storage

Connect Schedule to Agents

The Schedule Capability can let an Agent read or manage allowed Runtime Schedules through Capability policy. Inline Agent Schedules start the owning Agent with Schedule Invocation Input, not a synthetic user message.

Attach a Schedule Capability only when a model needs to manage schedules. Read Official capabilities for Capability modes and write policy.

Production checks

Schedule Runs, Schedule Run Attempts, retry policy, overlap policy, and dedupe policy belong to Schedule. Naming a policy does not imply every policy is configurable in the first version.

Static Schedule Definitions and Provider Wake output remain UTC. Runtime Schedules use UTC by default and can persist an IANA timeZone when local clock time must follow daylight-saving changes.

Next steps

• Use Queue when a provider-supported enqueue delay is enough.
• Use Workflows for durable orchestration.
• Learn trigger language in Channels API.