PR #68584: feat(plugins): add plugin-facing heartbeat and timeout timer seam for delegated tasks

• Repository: openclaw/openclaw
• Author: seoseo-ai
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/68584

Description (problem / solution / changelog)

Issue

Closes openclaw/openclaw#68551

Summary

Adds createDelegatedTaskWatchdog — a public seam that lets plugin-owned delegated-task code schedule heartbeat cadence and timeout cleanup without importing internal core timers directly.

Changes

src/plugins/delegated-task-watchdog.ts (new)

• DelegatedTaskWatchdogConfig — taskId, heartbeatCadenceMs, optional deadlineAtMs, onHeartbeat, onTimeout callbacks
• DelegatedTaskWatchdogHandle — .cancel(), .destroy(), .extend(newDeadlineAtMs), .active, .taskId
• Explicit teardown: no orphan timers after cancel/destroy
• Timers are .unref()'d to avoid blocking event loop exit
• Handler errors are caught and logged — never crash the watchdog loop

src/plugins/delegated-task-watchdog.test.ts (new)

• 13 test cases:
  1. Rejects invalid heartbeatCadenceMs
  2. Fires heartbeat ticks at configured cadence
  3. Fires onTimeout when deadline is reached
  4. Stops heartbeat after timeout fires
  5. cancel() stops all timers without firing onTimeout
  6. destroy() fires onTimeout with reason "manual"
  7. destroy() is idempotent — onTimeout fires at most once
  8. cancel() is idempotent
  9. extend() moves the deadline forward
  10. extend() with past deadline fires timeout immediately
  11. extend() is a no-op after cancel
  12. Reports remainingMs correctly with deadline
  13. Survives onHeartbeat handler throwing
  14. Survives onTimeout handler throwing

src/plugins/runtime/types.ts (modified)

• Added createTaskWatchdog method to PluginRuntime type
• Imports DelegatedTaskWatchdogConfig and DelegatedTaskWatchdogHandle

Design Decisions

• Factory pattern rather than a class — keeps it functional, easier to test and mock
• Unref timers — mirrors core-internal timer behavior for agent waits
• Error boundary around callbacks — a bad plugin callback never poisons the watchdog
• extend() — supports long-running tasks that need deadline extension mid-flight

Done When (from issue)

• Plugin-owned delegated-task code can schedule and cancel watchdog behavior through a public seam
• Timeout and heartbeat behavior can be exercised in tests without private core imports
• Cleanup behavior is explicit and covered by tests

Changed files

• src/plugins/delegated-task-watchdog.test.ts (added, +260/-0)
• src/plugins/delegated-task-watchdog.ts (added, +199/-0)
• src/plugins/runtime/types.ts (modified, +15/-0)