Why this matters

OpenClaw plugins increasingly need to create follow-up work that happens later, in the same session lane the user is already operating in: remind me in an hour, reopen this investigation tomorrow, schedule a follow-up agent turn after an approval window, or clean up a family of pending nudges when the workflow resolves.

Without a generic seam, plugin authors end up with two bad options:

• push product-specific scheduling logic into OpenClaw core; or
• own host cron details themselves, which leaks infrastructure concerns into every plugin.

This PR adds the narrow host-scheduler seam in the plugin SDK. Plugins can ask the host to schedule a future session turn and later clean up plugin-owned scheduled jobs by tag, while OpenClaw keeps ownership of cron naming, lifecycle, delivery routing, and cleanup semantics.

What kinds of plugins this could support

This seam is intentionally generic. It can support many plugin families without adding plugin-specific scheduling routes to core:

• Support and ops plugins: reopen or re-check incidents after a delay, schedule escalation nudges, or queue a follow-up diagnostic turn.
• CRM and sales plugins: create reminder turns for deal follow-ups, pending replies, or renewal check-ins.
• Approval and workflow plugins: schedule reminders while waiting on a human decision, then clean up all related nudges when the workflow resolves.
• Digest and assistant plugins: schedule a future turn that produces a recap, check-in, or status refresh in the same session lane.
• Import, migration, and reconciliation plugins: retry or re-check long-running work later without inventing a parallel scheduler stack.
• Research and monitoring plugins: schedule a revisit turn after some cooling-off period when an external dependency is expected to change.

The important part: the plugin decides why the follow-up exists. OpenClaw only provides the bounded host seam for when it should happen and how it is cleaned up.

New SDK seam

This PR adds:

• OpenClawPluginApi.scheduleSessionTurn(...)
• OpenClawPluginApi.unscheduleSessionTurnsByTag(...)
• typed schedule / cleanup params and result types in the SDK
• host-side support for at, delayMs, and cron schedules
• plugin-prefixed cron naming plus plugin-owned tag cleanup
• a narrow post-registration carve-out so only these two helpers remain callable after register()

Example plugin usage:

const reminder = await api.scheduleSessionTurn({
  sessionKey,
  delayMs: 60 * 60 * 1000,
  text: "Re-check whether the customer replied.",
  tag: "followup",
  deliveryMode: "announce/last",
  deleteAfterRun: true,
});

await api.unscheduleSessionTurnsByTag({
  sessionKey,
  tag: "followup",
});

Runtime architecture

flowchart LR
  Plugin["Plugin callback, handler, or workflow"] --> SDK["scheduleSessionTurn / unscheduleSessionTurnsByTag"]
  SDK --> HostHooks["Host hook workflow"]
  HostHooks --> Cron["Host cron naming and persistence"]
  Cron --> FutureTurn["Future agent turn in the same session lane"]
  Plugin --> Cleanup["Plugin-owned tag cleanup"]
  Cleanup --> Cron

The plugin owns the follow-up intent and tag taxonomy. OpenClaw owns the cron contract, namespacing, and actual future-turn delivery.

Safety and boundaries

This stays intentionally narrow:

• plugins do not get generic cron ownership or arbitrary background-job control
• only scheduleSessionTurn and unscheduleSessionTurnsByTag stay callable after register()
• cron job names are namespaced by plugin id so short tags do not clobber each other
• reserved cleanup tags are rejected instead of silently widening semantics
• invalid cron + deleteAfterRun: true combinations are rejected instead of guessing
• scheduled-turn records stay plugin-owned until lifecycle cleanup confirms the host job is gone

This is a scheduler seam for future session turns, not a generic host automation API.

What changed

• Added OpenClawPluginApi.scheduleSessionTurn and unscheduleSessionTurnsByTag plus SDK exports for schedule/cleanup params and results.
• Added host cron payload construction for at, delayMs, and cron schedules, with optional delivery mode.
• Added plugin-prefixed cron names and tag cleanup so two plugins can reuse short tags without clobbering each other.
• Rejected reserved : cleanup tags and rejected cron + deleteAfterRun: true instead of silently widening the host contract.
• Preserved plugin-owned scheduled-turn records until lifecycle cleanup confirms the host job is gone, instead of time-pruning those records early.
• Preserved the loader's closed-after-register guard for normal registration mutations, but let only scheduleSessionTurn and unscheduleSessionTurnsByTag remain callable after register() so a real bundled plugin can capture them during register() and invoke them later from a registered callback/handler.
• Added real-loader regression coverage for post-registration gateway-handler dispatch plus the invalid-tag / invalid-deleteAfterRun cases.
• Moved the changelog entry back under ## Unreleased and regenerated the plugin-sdk API baseline after the rebase.

Relationship to adjacent seams

This does not try to solve every workflow problem in one slice. It is intentionally narrower than session actions, run-context lifecycle, attachments, or SessionEntry projection. Those remain split into follow-up PRs so maintainers can review one host seam at a time.

Non-goals

• Does not widen the generic post-registration plugin API beyond these two operational helpers.
• Does not give plugins arbitrary cron ownership or a general background-job runner.
• Does not include session actions, host-mediated attachments, finalization retry/run-context lifecycle, tool-derived paths, SessionEntry projection, or advanced workflow composition fixtures.
• Does not claim to close broader Control UI/native-page RFC scope; this only adds the generic scheduled-turn seam.

Real behavior proof

Behavior or issue addressed:
This keeps the post-registration seam narrow while proving the scheduled-turn helpers work in a real host runtime. After this patch, a bundled plugin can capture scheduleSessionTurn and unscheduleSessionTurnsByTag during register(), invoke them later from a registered callback/handler, create real host cron jobs, reject invalid cleanup inputs without widening the contract, and clean up the tagged jobs deterministically.

Real environment tested:
On 2026-05-09, I started a real loopback gateway from /Users/lume/openclaw-review-worktrees/pr-75588-rebase and loaded a real bundled proof-scheduler plugin through loadOpenClawPlugins.

Exact steps or command run after this patch:

1. Loaded the bundled proof-scheduler plugin and let it capture api.scheduleSessionTurn plus api.unscheduleSessionTurnsByTag during register().
2. Invoked the registered plugin gateway handler proof-scheduler.exercise so the plugin exercised those captured helpers after registration.
3. Called cron.list immediately after scheduling to inspect the real host jobs.
4. Ran the cleanup phase through unscheduleSessionTurnsByTag, then called cron.list again to verify that the tagged jobs were gone.

Evidence after fix:

• The schedule phase returned two real handles:
  • 7d2d8bf2-f028-4a44-ad08-c75fd966b965
  • ca448912-25a0-4aec-9e87-88587464e0dc
• The invalid tag: "bad:tag" case returned null.
• The invalid cron + deleteAfterRun: true case returned null.
• cron.list immediately after schedule showed two real host jobs named plugin:proof-scheduler:tag:proof:agent:main:main:*, both targeting session:agent:main:main, both deleteAfterRun: true, with delivery modes announce/last and none, and with scheduled at timestamps 2026-05-09T17:08:00.334Z and 2026-05-09T17:09:00.356Z.
• The cleanup phase returned { removed: 2, failed: 0 }.
• cron.list after cleanup returned [].

Copied live output after fix:

$ proof-scheduler.exercise
first.id=7d2d8bf2-f028-4a44-ad08-c75fd966b965
second.id=ca448912-25a0-4aec-9e87-88587464e0dc
badTag=null
badDelete=null

$ cron.list
plugin:proof-scheduler:tag:proof:agent:main:main:* deleteAfterRun=true delivery=announce/last at=2026-05-09T17:08:00.334Z
plugin:proof-scheduler:tag:proof:agent:main:main:* deleteAfterRun=true delivery=none at=2026-05-09T17:09:00.356Z

$ unscheduleSessionTurnsByTag
{ removed: 2, failed: 0 }

$ cron.list
[]

Observed result after fix:
The real bundled plugin was able to use the two late-call helpers after register() without reopening the rest of the plugin API. Real host cron jobs were created, visible in cron.list, and then removed cleanly by the tagged cleanup path. Invalid cleanup tags and invalid cron + deleteAfterRun: true combinations were rejected instead of silently widening the contract.

What was not tested:
This proof did not cover a full user-facing UI flow or a long-lived production cron lifecycle across process restarts. The live proof here is intentionally limited to real post-registration helper capture, real host cron job creation/listing, invalid-input rejection, and tagged cleanup in a live OpenClaw runtime.

Validation

• pnpm test src/plugins/contracts/scheduled-turns.contract.test.ts src/plugins/contracts/host-hooks.contract.test.ts
• pnpm plugin-sdk:api:gen
• pnpm plugin-sdk:api:check
• pnpm lint:core
• git diff --check
• npm run check:no-conflict-markers