mirror of https://github.com/qwibitai/nanoclaw.git synced 2026-07-09 18:57:08 +08:00

Files

T

Omri Maya b0c76ce4c5 feat(tasks): ncl tasks control plane — isolated per-series sessions, strict verb contract, script gate

Scheduled tasks move from MCP tools to a first-class ncl resource:
list / get / create / update / cancel / pause / resume / run / append-log,
with args declared on every verb (strict validation, fix-carrying errors)
and deep per-verb help with executable examples.

A series is CronJob-like: the live (pending/paused) row is the next
occurrence, completed rows are its run history. tasks list reads as a
compact run-history table, server-rendered so the container agent prints
the same aligned table. Short named ids (<slug>-<hex>) are
filesystem/thread-safe and copy-pasteable. Agents keep a per-series work
journal: the run log at tasks/<series>.md (append-log + auto-logged
final text).

Each series runs in its own isolated system session
(system:tasks:<series>); the live-task cap is dropped — isolation
replaces throttling. Spent task sessions are GC'd by the sweep.

--script on a task runs a bash gate BEFORE the agent wakes. It prints a
JSON verdict as its last stdout line: {"wakeAgent": bool, "data": {...}}.
wakeAgent:false handles the occurrence without waking the agent; data is
threaded into the fire's prompt, so a gate can fetch/inspect and hand the
agent exactly what changed. Failing scripts back off exponentially
(2·2^(n-1) min, cap 60) and auto-pause the series after 8 consecutive
failures with a host-written run-log note; manual runs are excluded from
the streak.

BREAKING: the schedule_task / list_tasks / update_task / cancel_task /
pause_task / resume_task MCP tools are removed. Agents schedule via
ncl tasks (available under cli_scope=group). Existing task rows keep
firing — storage (messages_in kind='task') is unchanged; only the
management surface moved. Migration: docs/ncl-tasks-migration.md.
Review round (gavrielc):
- Recurrence frequency guard: create/update refuse a recurrence more
  frequent than 4 fires/day with a warning steering to gate scripts;
  --dangerously-override-recurrence-limit bypasses after explicit user
  confirmation. Counted over the next 24h in the instance TZ. Guarded on
  update too, so create-slow-then-update cannot sneak past.
- ncl tasks help scripts: resource help topics (new helpTopics seam on
  registerResource) carry the full gate-script guide — contract, examples,
  state, failure/backoff semantics, testing directions.
- Agent-facing scheduling instructions slimmed: no recurring-frequency
  prose in the fragment; one pointer to the help topic.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-08 17:04:45 +03:00

2.7 KiB

Raw Blame History

`ncl tasks` migration

Detect

If an agent mentions schedule_task, list_tasks, update_task, cancel_task, pause_task, or resume_task, it is using the old scheduling MCP surface.

A subtler symptom of a stale container image: the agent reports a task as scheduled, but ncl tasks list shows nothing and the host log has Unknown system action — the old image's schedule_task call is acknowledged in-container and then dropped by the new host. The fix below (rebuild + restart) resolves it.

Why

Scheduling moved to ncl tasks. New tasks are stored in a per-agent-group system session and run there, so a scheduled task does not wake an existing chat session. When it fires, the agent must choose the delivery destination explicitly.

Fix

Rebuild and restart agent containers so they load the updated MCP tool list and instructions:

./container/build.sh
launchctl kickstart -k gui/$(id -u)/com.nanoclaw

On Linux, restart with systemctl --user restart nanoclaw.

Use:

ncl tasks list
ncl tasks create --group <agent_group_id> --prompt "..." --process-after "2026-01-15T09:00:00" --recurrence "0 9 * * *"
ncl tasks update --id <series_id> --prompt "..."
ncl tasks cancel --id <series_id>

Verify

Run ncl tasks list. New task rows should show a system session_id, not the chat session that requested the task.

Legacy tasks (scheduled before this update)

Tasks created through the old MCP tools live in the chat session that created them, not in a per-series system session. They are unaffected by this update: they keep firing and delivering exactly as before. Two things to know:

An agent's own ncl tasks list (group scope) shows only its group's task rows; from the host, unscoped ncl tasks list enumerates everything, and --session <id> narrows to one session — that is how you find and manage legacy rows (ncl tasks cancel --session <chat_session_id> --all to clear a chat session's tasks).
The messages_in status enum now includes cancelled (cancel marks the row and clears its recurrence rather than deleting it). Custom code that exhaustively switches on task status needs the new arm.

Rollback

Order matters:

Remove tasks created through ncl tasks (ncl tasks list / delete) — they live in per-series system sessions the old code doesn't know about.
Wait one sweep (≤60s) so the host closes the now-empty task sessions.
Then revert the update and rebuild the container image.

Reverting before the task sessions are collected leaves system sessions behind that the old findSessionByAgentGroup (which has no system-session exclusion) can resolve as the group's session — mis-routing agent-to-agent messages into a dead task thread.

2.7 KiB Raw Blame History

ncl tasks migration