tasks

​

Summary

​

Environment variables

​

Depends on

​

What it contributes

• Tools (10, on-demand): the agent loads them via the capability gate before use.
  • preview_task — run a candidate spec once, for real, and return the output + a previewToken. Always required before scheduling; the agent must show the user this output and stop.
  • create_task — schedule a previewed task. Requires a matching previewToken minted in an earlier turn (re-preview if anything changed). Picks time.once vs time.cron and the delivery room.
  • list_my_tasks — list the user’s tasks (id, title, status, trigger, next run); optional status filter.
  • get_task — full spec body, status, trigger, delivery room, and the last error if it has been failing.
  • update_task — patch title, trigger, approval mode, or intent. Changing the intent needs a fresh previewToken; changing the trigger reschedules automatically.
  • pause_task — pause a task; pending runs are cancelled until resumed.
  • resume_task — resume a paused, pending-approval, or failed-pending-review task; recomputes the next run.
  • cancel_task — cancel permanently (spec kept for the audit trail).
  • resolve_task_approval — record the user’s decision (approved / declined) after a nuanced reply in a [Task] room. Plain yes/no replies are recorded automatically — don’t call this for those.
  • suggest_spec_fix — for a failing task, return the current body + last error so the agent can propose a revision (applied via update_task only after the user agrees).
• Sub-agents: none.
• Middleware: one — TaskRoomApprovalGate. Wraps every model call but only acts inside a dedicated task room whose task is pending-approval. A plain yes/no reply is classified and resolved deterministically before the model runs; nuanced replies get a system-prompt hint pointing the model at resolve_task_approval. It never short-circuits the turn and never posts to Matrix.
• HTTP routes: none.
• Nest module: TasksModule — owns the BullMQ task_run queue + TaskRunWorker, a Redis-backed state/task store, the scheduler, delivery service, agent invoker, and approval flow. On init it registers a room→session resolver on the Matrix bridge so a plainly-typed reply in a task room continues that run’s own thread instead of starting a fresh one.
• Shared state: none.

​

Triggers

​

The preview → create flow

​

Before-action approval

• A plain “yes” / “no” (and close variants) is recorded deterministically by the TaskRoomApprovalGate middleware before the model runs.
• A nuanced reply (“fix the typo first, then send”) is handled by the agent, which acts on it and then calls resolve_task_approval.

​

Task statuses

​

Opt out / Opt in

const app = await createOracleApp({
  config,
  features: { tasks: false }, // never load
  // features: { tasks: true }, // force load (fails env validation if REDIS_URL missing)
  // features: { tasks: 'auto' }, // run autoDetect (default — loads when REDIS_URL is set)
});

​

When to use it

• The user wants a reminder or recurring report (“every morning at 7”, “tomorrow at 5pm”, “remind me to…”).
• The user wants the agent to monitor or track something on a schedule.
• The user wants a piece of work run later, in the background, without sitting in the chat.

​

When NOT to use it

• A one-shot action the user wants done right now — just do it inline.
• Real-time / streaming requirements — tasks run on a scheduled cadence, not on demand.

​

Where to read next