task Plugin
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
lifecycleactionssystem
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
The CLI invokes task through the shared Plugin Action command:
city plugin action task list <agent_id> --input '{}' --token <token>
city plugin action task run <agent_id> --input '{"title":"daily-summary","reason":"manual check"}' --token <token>Use the task Plugin when automation should remain named, editable, and manually runnable, instead of adding another top-level CLI special case.
SDK Assembly
TaskPlugin only needs the optional timezone setting. Agent tasks use the effective model of the bound Session, preferring its model and falling back to the Agent model. By default, cron uses the current machine timezone:
import { TaskPlugin } from "@downcity/plugins/task";
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.run_action({
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 - agent tasks read the effective runtime model from the Session port in PluginContext
- 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; the CLI invokes it through the shared city plugin action command.