Task Tools Plugin

The Task Tools plugin lets the agent (or you, through it) create, inspect, and manage scheduled agent runs — one-off (run_at) or recurring (cron). Each run fires as a fresh conversation seeded with the stored prompt; there is no context carry-over between runs.

Configuration

plugins:
  - module: codumentor.plugins.task_tools
    class: TaskToolsPlugin
    priority: 10
    args:
      enabled: true
      allow_cron: true
      default_timezone: UTC
      run_history_retention_days: 365

Parameter	Type	Default	Description
enabled	bool	true	Enable or disable the plugin.
allow_cron	bool	true	Allow recurring (cron) tasks. When false, only one-off run_at runs are permitted.
default_timezone	string	"UTC"	IANA timezone for interpreting cron expressions.
run_history_retention_days	int	365	How long to keep finished run history — and the per-run conversations, which are soft-deleted first — before a maintenance sweep purges them. 0 or negative keeps history forever.
retention_sweep_interval_seconds	float	86400	How often the maintenance sweep runs (retention purge plus stale-run cleanup). A restart also sweeps immediately.
stale_run_threshold_seconds	float	3600	A run that has been running with no progress longer than this is treated as stuck and marked failed.
parked_run_ttl_seconds	float	604800	How long a run whose turn is waiting on an approval may wait. Past it, the maintenance sweep ends the run as failed (stale) and drops its token ledger. A waiting run is never treated as stuck by the threshold above. 0 disables.
target_agents	string	"main"	Which agents get the task engine tools: "main", "subagent", or "all". Default keeps scheduling off subagents (their tool calls have no human reading them). A scheduled run itself is a main agent, so it can still manage tasks.

One switch this plugin reads but does not own: tasks.allow_agent_created
(default true), in the server's tasks: block rather than here, because it is
a statement about the task engine's authorization boundary rather than about
which tools this plugin ships. false makes create_task refuse — see
Admin Configuration Reference.

Tools

Tool	Description
create_task	Create a one-off (run_at), recurring (cron) or event-fired (on, with optional scope / when / mode / debounce_seconds) run; returns a schedule_id. Exactly one of the three. Only in-instance event types may be used — task., job., kb., plugin.; the ones that arrive from outside (repo., scm., webhook.*) are operator-declared in the server config only. access_profile names the profile the unattended run executes under. Optional per-run limits: timeout_seconds (wall clock, max 6h) and token_budget (tokens, minimum 1000).
list_tasks	List the caller's tasks (optional status filter)
get_task	Full detail for one task, including last-run state
update_task	Change timing, timezone, title, prompt, or the per-run limits timeout_seconds / token_budget. Passing null for a limit removes the task's own value, so the default applies again (the operator's token budget, the job queue's timeout).
pause_task / resume_task	Pause or resume a task
snooze_task	Postpone the next fire to a given time
cancel_task	Permanently cancel a task
list_task_runs	List prior runs of a task (most recent first), with status / error_kind, timings and tokens (input, cached, cache-write, output, total, cost_usd — null = unknown — and the run's effective token_budget, null = unlimited)
get_task_run_output	Fetch a run's prompt, final answer, and turn summary
list_events	Read the trigger event ledger — "did the webhook arrive?", "why did that task run?"
list_event_types	The event types a trigger can fire on, with each type's payload paths (what a when: clause may test and bind: may substitute), what emits it, and how its scope/dedupe keys are formed. Pass type for one type in full detail — kinds, required fields, and which values are untrusted. Read this before writing an on:: the type is a closed vocabulary, and a typo makes a trigger that never fires rather than an error.
test_trigger	Dry-run a trigger (a saved task, or an inline on/scope/when) against an event (a ledger event, or an inline one) and get back the stage that decided — the event type, the scope, a named when[i] clause with the value found at its path, a paused task, or the provenance guard. A malformed clause is reported as invalid, not as "no match".

Notes

• You can only see and modify your own tasks (test_trigger included, when it is given a task_id). list_events is the exception: an event is an instance-level fact (a push arrived, an ingest finished), not something with an owner, so the ledger is not scoped per user. Raw webhook bodies are never returned by it.
• A card in the conversation shows when a scheduled run starts and finishes.
• Per-task timeout_seconds overrides the job queue's default timeout.
• Per-task token_budget caps one run's agent tokens — every token sent to or received from the model, cached prompt tokens included, subagents and external agents included; auxiliary calls (auto title, summaries, memory recall, judges, compaction) are not counted. Without one, the operator's tasks.default_run_token_budget (or default_webhook_run_token_budget for webhook-fired runs) applies, and tasks.max_run_token_budget caps any value. The run is checked at the top of each agent-loop iteration, so it can overshoot by up to one iteration; the agent is told to wrap up at 80 %. A run that spends its budget ends failed with error_kind: token_budget and counts toward the task's auto-disable like a timeout. A run whose model the loop detector stops (it kept repeating the same step) likewise ends failed, with error_kind: loop. See Admin Configuration Reference → Per-run token budgets.
• The finished run card shows the run's tokens (Tokens: 84.2k (in 80.1k, cached 61k, out 4.1k)), its budget and % used when it had one, and its cost — unknown for a model without a price, never $0.
• A run whose turn waits on an approval stays running and keeps its budget when resumed; past parked_run_ttl_seconds it ends failed (stale). This bookkeeping is in memory: after a server restart such a run ends failed (stale) and its turn is not continued.
• For multi-worker, knowledge-base-coordinated long-running intents built on top of the task engine, see the Goals plugin.