Task definitions, task actions, and cron-trigger runtime owned by one plugin instance

`task` Plugin

task is the task runtime plugin.

It owns:

task-facing actions
task system text
one cron trigger engine per plugin instance

Main shape

lifecycle
actions
system

What it is for

Use task when you need:

task definitions and mutations
cron-triggered task execution
scheduler reload after task changes

How users use it

Use downcity task when you want a reusable task definition:

downcity task list
downcity task create --title "daily-summary" --description "Send a daily summary" --when "0 9 * * *" --session-id <sessionId>
downcity task run daily-summary --reason "manual check"
downcity task update daily-summary --status paused
downcity task enable daily-summary
downcity task disable daily-summary
downcity task delete daily-summary

Use downcity chat send --delay/--time or another plugin action with --delay/--time for a one-shot delayed action. Use downcity task when the automation should remain as a named, editable task.

SDK Assembly

TaskPlugin can be used with no options. By default, it uses the current machine timezone. If cron tasks should use a fixed timezone, pass timezone at the constructor root:

import { TaskPlugin } from "@downcity/plugins";

const plugin = new TaskPlugin({
  timezone: "Asia/Shanghai",
});

timezone mainly affects cron expressions. One-shot time:<ISO8601-with-timezone> tasks use the timezone offset embedded in the ISO string itself.

SDK action use

await agent.plugins.runAction({
  plugin: "task",
  action: "run",
  payload: {
    title: "daily-summary",
    reason: "manual check",
  },
});

The action names are list, create, run, delete, update, status, enable, and disable.

Important semantics

long-lived cron runtime belongs to the plugin instance
cron timezone comes from constructor timezone, defaulting to the local machine timezone
task scheduler reload is triggered after create, update, delete, or status mutation
the running-task lock belongs to the plugin instance, so reloads still keep each task serial
the plugin can also accept lifecycle commands such as reload or reschedule

Public status

TaskPlugin is exported from @downcity/plugins. It can be attached directly in SDK usage, although the most common path is still through the agent runtime and downcity task.

task Plugin