openclaw - ✅(Solved) Fix [RFC] Agent events, run context, scheduler lifecycle, and heartbeat contributions [1 pull requests, 1 comments, 1 participants]

openclaw2026-04-25 19:57:58

ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

GitHub issue URL

Helpful · Quick feedback

GitHub stats

openclaw/openclaw#71737•Fetched 2026-04-26 05:09:02

View on GitHub

Comments

Participants

Timeline

Reactions

Author

100yenadmin

Participants

100yenadmin

Timeline (top)

commented ×1cross-referenced ×1

Expose safe plugin subscriptions to agent events, namespaced run-scoped plugin context, session-scoped scheduler helpers, and heartbeat prompt contributions.

This is proposed SDK surface, not currently implemented API.

Root Cause

Plan Mode parity requires plan snapshot persistence, subagent tracking, run completion cleanup, scheduled nudges, and heartbeat prompt nudges. Plugins need stable helpers for those behaviors without raw event-bus access or manual cron cleanup.

The same primitive applies to telemetry exporters, memory indexers, CI/deploy monitors, incident/ticket bots, channel notification plugins, long-running job monitors, and subagent coordinators.

Code Example

api.onAgentEvent("run_completed", handler);
ctx.runContext.set("plugin-key", value);
ctx.scheduler.createSessionJob({ pluginKey, sessionKey, kind, schedule, payload });
api.on("heartbeat_prompt_contribution", handler);

RAW_BUFFERClick to expand / collapse

Summary

Expose safe plugin subscriptions to agent events, namespaced run-scoped plugin context, session-scoped scheduler helpers, and heartbeat prompt contributions.

This is proposed SDK surface, not currently implemented API.

Why this matters

The same primitive applies to telemetry exporters, memory indexers, CI/deploy monitors, incident/ticket bots, channel notification plugins, long-running job monitors, and subagent coordinators.

Current SDK surface

OpenClaw currently has runtime.events.onAgentEvent, internal AgentRunContext, hook contexts with run/session identifiers in some paths, gateway_start.getCron, generic prompt hooks, and heartbeat request helpers.

Those surfaces are useful but insufficient: raw event observation is not a typed lifecycle-owned plugin API; cron access does not provide plugin/session ownership cleanup; prompt hooks are not heartbeat-specific; and there is no namespaced plugin run-context storage that the host cleans on run completion.

Proposed solution

Add typed event subscription and lifecycle helpers such as:

api.onAgentEvent("run_completed", handler);
ctx.runContext.set("plugin-key", value);
ctx.scheduler.createSessionJob({ pluginKey, sessionKey, kind, schedule, payload });
api.on("heartbeat_prompt_contribution", handler);

The host should sanitize event payloads, enforce event access rules, own cleanup on run end/session reset/plugin disablement, and define deterministic heartbeat contribution ordering.

Reusable plugin examples

Plan Mode persists plan snapshots, tracks blocking subagents, schedules nudges, and contributes heartbeat reminders.
Telemetry exporters subscribe to sanitized events and batch scheduled exports.
Memory indexers observe run/tool events and refresh derived context.
CI watchers poll workflows and inject completion or failure summaries.
Incident bots schedule SLA escalations and heartbeat unresolved incidents.
Channel plugins track delivery events and retry failed sends.
Long-running job monitors poll job state, emit progress, and clean up on session close.
Subagent coordinators store per-run state and inject follow-up once subagents settle.

Decisions needed

Event types exposed to plugins and which require trust.
Run-context storage lifecycle and namespace model.
Session-scoped scheduler ownership and cleanup model.
Dedicated heartbeat hook vs heartbeat-scoped agent_turn_prepare.
Cleanup behavior on run end, cancellation, session reset/delete, gateway restart, and plugin disablement.
Diagnostics for dropped events, failed jobs, and suppressed heartbeat contributions.

Acceptance criteria

Fixture plugin observes one sanitized agent event.
Fixture plugin writes derived extension state from that event.
Run context data is available during a run and cleaned after completion/cancellation.
Session reset deletes fixture-owned scheduled jobs.
Plugin disablement removes fixture jobs and heartbeat contributions.
Heartbeat contribution appears only when fixture session state requests it.

References

RFC PR: https://github.com/openclaw/openclaw/pull/71731
Source behavior/parity oracle: https://github.com/openclaw/openclaw/pull/71676
Full RFC packet: docs/plan/plan-mode-plugin-host-hooks-rfc.md

extent analysis

TL;DR

Implement a namespaced plugin context and session-scoped scheduler helpers to expose safe plugin subscriptions to agent events and heartbeat prompt contributions.

Guidance

Review the proposed SDK surface and ensure it meets the requirements for plan mode parity, including plan snapshot persistence and scheduled nudges.
Determine the event types to be exposed to plugins and the trust requirements for each event type.
Define the lifecycle and namespace model for run-context storage and session-scoped scheduler ownership.
Implement cleanup behavior for run end, cancellation, session reset, gateway restart, and plugin disablement.

Example

api.onAgentEvent("run_completed", handler);
ctx.runContext.set("plugin-key", value);
ctx.scheduler.createSessionJob({ pluginKey, sessionKey, kind, schedule, payload });
api.on("heartbeat_prompt_contribution", handler);

Notes

The proposed solution requires careful consideration of event access rules, cleanup behavior, and deterministic heartbeat contribution ordering to ensure a stable and secure plugin API.

Recommendation

Apply the proposed solution to implement a namespaced plugin context and session-scoped scheduler helpers, as it provides a clear and structured approach to exposing safe plugin subscriptions to agent events and heartbeat prompt contributions.

Vote matrix · Quick signals

Works

Did the solution work? Tap to confirm.

Easy Fix

Was it a quick fix?

Time Saver

Did it save you time?

Blocking

Was it severely blocking?

Common Issue

Are others likely hitting this too?

Flaky / Intermittent

Is it intermittent?

Verified / Reproducible

Can you reproduce it reliably?

#api #ssr #installation #API versioning #request timeout

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

openclaw - ✅(Solved) Fix [RFC] Agent events, run context, scheduler lifecycle, and heartbeat contributions [1 pull requests, 1 comments, 1 participants]

Recommended Tools

GitHub issue graph ai analysis

Root Cause

Fix Action

Fixed

PR fix notes

PR #71731: docs: add Plan Mode plugin host hook RFC

Description (problem / solution / changelog)

Summary

RFC Status Warning

RFC Decision Threads

RFC Contents

Change Type

Scope

Linked Issue/PR

Verification

Human Verification

Compatibility / Migration

Risks and Mitigations

Next Step After This PR

Changed files

Code Example

Summary

Why this matters

Current SDK surface

Proposed solution

Reusable plugin examples

Decisions needed

Acceptance criteria

References

extent analysis

TL;DR

Guidance

Example

Notes

Recommendation

Still need to ship something?

RELATED_DISCOVERY

TRENDING