task Power

Manage personal todos, agent work, inbox items, and schedules

task captures work, runs agents, and schedules recurring occurrences in one task model. TaskPower owns domain behavior without a renderer. Desktop provides Memo, Needs attention, and task collections in List, Board, Calendar, and Timeline. Each task uses one BayBar tab with Task, Delivery, and History as applicable; agents handle the same domain records from chat.

Task identity

Each task has a stable task_id. Titles are editable and may repeat. create returns the ID; list includes IDs and workflow properties. Prefer IDs for subsequent operations.

Existing actions use a selector named title. Pass a stable task ID or a unique title. Ambiguous titles fail explicitly.

Actions

ActionPurpose
generateUse an internal model to generate a task, validate and save it, and directly apply its arrangement. Pass task_id to revise or retry.
createValidate and save structured task fields without an internal model or another confirmation.
listList the current agent's execution tasks and personal todos.
updateEdit the title, instructions, or schedule.
runStart agent/script execution; optionally retry a recurring occurrence_id.
history / run_detailRead execution records and deliverables.
inboxRead unorganized work and unresolved items without resolving them.
workOrganize, start, complete, reopen, accept, request changes, or handle a specific item.
status / enable / disableControl scheduling independently of work completion.
deleteDelete work and its history; active executions prevent deletion.

For natural language, call generate, for example { "text": "Prepare Friday's demo" }. Agent requests and explicit task creation from memo selections use this action. Desktop's BayBar editor generates read-only draft suggestions separately; the user checks and explicitly saves them, with Save and run for immediate execution. Successful generation directly saves and applies the arrangement. Recording work does not start it; explicit immediate-execution requests start work, while timed or recurring work waits for its trigger. Generation failures preserve task_id; reuse a client submission_id when retrying a new submission. Prefer create when structured fields are already known; manual work starts through run only when requested. One-time triggers must include a timezone and be in the future. The originating session and delivery target are captured automatically.

Create a personal todo:

{ "title": "Prepare Friday's demo", "kind": "user" }

An Agent task's body contains only the goal, steps, constraints, and deliverable for one execution, instructing the executor to complete the current task directly and return its deliverable. Keep Cron, recurrence, trigger times, and timezones in separate fields such as when and timezone. The body contains no scheduling arrangements or instructions to create, schedule, or delegate another task.

Create scheduled agent work:

{
  "title": "Daily report",
  "kind": "agent",
  "when": "0 9 * * *",
  "timezone": "Asia/Shanghai",
  "description": "Summarize daily progress",
  "body": "Read project records and deliver progress, blockers, and next steps. The final reply must be the report body itself."
}

Accept a result using the task and original Inbox item IDs:

{ "task_id": "task_example", "command": "accept", "item_id": "review:example" }

Accept only after explicit user confirmation. Agents should not approve their own deliverables.

Work and execution

Personal work (kind=user) needs no Agent or Workspace. Scheduled personal work creates a reminder. Agent/script work uses its configured execution targets. One-time agent work awaits human acceptance; recurring work completes each successful occurrence by default, with optional per-occurrence acceptance in task details.

when supports @manual, time:<ISO datetime with timezone>, and Cron. Use 0 20 * * * or cron:0 20 * * * for a daily trigger at 20

in the task timezone; the cron: prefix is removed when saved. Enter stars as * without backslash escaping. Due dates do not trigger execution. Each recurring occurrence has an independent completion record.

Agent tasks execute in independent Sessions with origin.type = "task", which is separate from task configuration kind=user/agent/script. Task Power is disabled in both Task executor and simulated reviewer (user_simulator) Sessions. Neither may dispatch another Session through session.start or agent.delegate. The executor completes the current task directly, and its final reply is the deliverable body itself.

Questions, approvals, and secret input remain in the original execution Session for the user to handle through the shared interaction interface. Approvals and private input must use their original trusted entry points. The Task page does not provide a general reply entry point for questions in active executions.

Automatic scheduling requires a running City. Missed one-time plans appear in Inbox; missed offline recurring triggers are not replayed. Active tasks cannot yet be edited or cancelled from the Task page. Late results cannot wake the original execution after it stops.

Agent work created in chat can return results to its original Session. Results can still be queued for asynchronous handling after the original Chat Turn has finished or been stopped. Stopping Chat's current reply does not cancel the background Task execution. Changing execution targets does not change the delivery destination. Tasks created without a Session retain results in execution history. Explicitly instruct the executing agent to use Messenger when external delivery is required.

Host integration

In browsers and Electron renderers, import task_status_label from @downcity/powers/task/presentation to display task status consistently. This entry contains only presentation functions and types, without Node.js scheduling dependencies. Import TaskPower from @downcity/powers/task in Node.js or the Electron main process; use import type for frontend type references to that entry.

Read Task Power for workspace and scheduling guidance.