Schedule

schedule() covers two schedule-related Agent abilities. It can declare fixed Agent Schedules as Capability metadata, or it can expose one cronjob tool for Runtime Schedules when configured with a mode.

Static Agent Schedule mode records one or more five-field UTC cron expressions on the Capability. Runtime Schedule mode contributes one cronjob tool. Read mode supports targets, list, and get. Write mode also supports create, edit, pause, resume, run, and delete.

Configure schedules

Use static schedules to run the Agent on known cron entries. ViteHub derives a stable id from the cron expression when you do not provide one.

import { defineAgent } from 'vite-hub/agent'
import { schedule } from 'vite-hub/agent/capabilities'

export default defineAgent({
  driver: { model },
  capabilities: [
    schedule({
      schedules: ['0 9 * * 1'],
    }),
  ],
})

To let an Agent create recurring turns for itself, enable self-targeting. ViteHub derives the target from the discovered Agent name and stores the prompt with a metadata-free copy of the resolved invoker identity. Every run passes through the Agent's normal Capability policies and agent:input hooks again. When invoker.resolve is configured, ViteHub also reruns it and continues only when the resolved id and kind still match. Without a resolver, ViteHub restores the durable identity; it does not perform external authentication automatically.

import { defineAgent } from 'vite-hub/agent'
import { schedule } from 'vite-hub/agent/capabilities'

export default defineAgent({
  driver: { model },
  capabilities: [
    schedule({
      allowSelfTarget: true,
      delivery: 'origin',
      mode: 'write',
      timeZone: 'Asia/Bangkok',
    }),
  ],
})

The Agent can now create a cron job with a prompt, such as a daily report. Only an invocation with the same resolved invoker id and kind can inspect or manage that scheduled turn. delivery: 'origin' sends the result back to the channel thread where the schedule was created. Creating that schedule fails when the invocation has no deliverable channel thread.

How schedules work

Static schedules add metadata that framework integrations and schedule-aware runtime behavior can inspect. Runtime Schedule mode reads visible Runtime Schedules and can create, edit, pause, resume, run, or delete scoped schedules when write mode is enabled. The cronjob tool accepts an optional IANA timeZone on create and edit, while schedules without one continue to use UTC. A configured timeZone provides the default for new schedules; edits change it only when the tool supplies a new value.

Requirements

Static schedules require at least one five-field UTC cron expression. Runtime Schedule mode requires a configured schedule primitive.

Runtime Schedule edits require explicit write mode and are allowed by default. Self-targeting requires explicit self-target permission. Runtime Schedules still require a provider wake or a long-running Schedule runner to execute when due. Set policy: 'require-approval' or policy: 'deny' when mutations need an additional gate; read operations remain allowed.

Driver support

Verify schedules

Inspect Capability metadata for static schedule ids and cron expressions. For Runtime Schedule mode, inspect the tool list and verify it contains only cronjob for scheduling. Its schema exposes only read operations in read mode.

Run a schedule with a six-field cron expression during development. Confirm that the Capability rejects it before the Agent starts.

Options

Related pages

• Schedule primitive
• Agent triggers