Task Plugin
How the Task plugin schedules and runs background jobs
Task Plugin
The Task plugin lets your Agent schedule and run background jobs. It is useful for periodic data fetching, report generation, or any work that should happen outside the normal request-response flow.
What it does
- Schedules tasks to run at specific times or intervals
- Persists Task definitions and run artifacts in one City-level Plugin store
- Restores enabled schedules when TaskPlugin initializes
- Prevents overlapping runs of the same Task
Desktop workspace
Task does not declare Config. It remains visible in the Plugins Catalog for its documentation and also contributes a top-level navigation entry. Its Plugin Sidebar uses a Task → runs tree: clicking a Task opens its definition, while expanding it loads run history. The Mainview shows the Task definition, final output, status, trigger, duration, validation, and failure details.
Desktop can create, edit, enable, pause, run, and delete Tasks directly. Tasks are not grouped by Agent or Workspace: each Task stores one rebindable agent_id and one workspace_id as execution targets, and the UI only shows their display names. A Task remains visible, editable, and removable when either target disappears. Deletion is rejected while the Task is running so its run artifacts cannot be removed concurrently. Definitions, scheduler state, and run artifacts are read from TaskPlugin's unified City lifecycle storage instead of an Agent-specific copy.
If a definition is saved but scheduler synchronization fails, Desktop explicitly reports that the Task was saved while scheduler synchronization failed. The committed definition is not rolled back or presented as a complete success; reload the Task scheduler after resolving the failure. A missing or invalid task.md appears as an error item in the Task page and is not scheduled. It neither disappears silently nor blocks other valid Tasks or Desktop startup, and it can be deleted from the page.
After a successful or failed Task persists its execution record, it publishes an unread item through the shared Notification module; skipped executions do not notify. Only the latest unread Run is retained for the same Task. Desktop shows a blue dot on the Task top-level icon, Task item, and matching Run, updates the system app badge, and marks the item read when that Run is opened.
Defining a task
Each Task is defined once in TaskPlugin lifecycle storage. TaskPlugin restores enabled definitions at initialization and enters the declared Agent/Workspace context only when a run is triggered by:
- Cron expressions
- One-shot scheduling
- Event-driven triggers
Use cases
- Daily data sync
- Periodic report generation
- Background file processing
- Scheduled notifications
Each run creates an independent task Session while reusing the execution Agent's capabilities. When create is called from an Agent Session, the runtime fixes the current Agent, Workspace, session_id, and origin.type as the delivery target. Rebinding the execution Agent or Workspace later changes only the execution target; City still appends the completed result to the original Session. The task Session inherits the source model only while execution and delivery still use the same Agent and Workspace. The model does not provide Session routing. Tasks created from CLI, HTTP, or host management surfaces without a Session context keep their results in Task run history. If the task Agent needs to send a chat message, it calls the Chat plugin from the task Session.
Continue with: