patleeman/neon-pilot/async-attention

Async Attention and Wakeups

Use the smallest scheduling surface that matches the owner of the work. For wait-then-continue requests, use the unified conversation deferred-resume admin command; do not run sleep in bash.

Choose the right surface

There is no standalone tell-me-later tool. Human “tell me later” requests are same-thread follow-ups unless they need a true app-wide automation.

the unified conversation deferred-resume admin command

Use the unified conversation deferred-resume admin command when this same conversation should continue later.

Actions:

• add — queue a follow-up
• list — list pending follow-ups for this conversation
• cancel — cancel a queued follow-up by listed id

For action: "add", always include trigger:

• trigger: "after_turn" queues work after the current turn; do not include delay or at.
• trigger: "delay" queues a later continuation; include compact duration syntax like 30s, 10m, 2h, 4h, or 1d.
• trigger: "at" queues a later continuation for a specific timestamp or human time phrase.

Example:

{
  "action": "add",
  "trigger": "delay",
  "delay": "4h",
  "deliverAs": "followUp",
  "title": "Check release state",
  "prompt": "Wake up and check whether the release is ready. If it is still blocked, requeue instead of asking the user."
}

Use the unified conversation deferred-resume admin command with action: "list" before assuming no wakeups are pending.

Do not schedule a the unified conversation deferred-resume admin command just to poll a running background command/subagent that was started with deliverResultToConversation: true. That run already owns completion/failure delivery. Only schedule a wakeup for a distinct time-based action that should happen regardless of completion timing, and include a clear reason.

scheduled_task and heartbeats

Use scheduled_task for app-wide recurring or one-time automations, especially work that can run without this conversation being active.

For recurring conversation self-admin callbacks, use the unified Neon Pilot admin surface instead: neon-pilot heartbeats start/list/stop externally or the internal neon_pilot tool actions heartbeat_start, heartbeat_list, and heartbeat_stop. Heartbeats are backed by scheduled conversation automations and coalesce by skipping due ticks while the target conversation is already running.

Do not

• invent a shared inbox substitute for ordinary async work
• use scheduled tasks for a simple same-thread follow-up
• use bash + sleep as a timer for deferred conversation work
• store async state only in notification/alert state
• copy conversation ids into portable durable files