Summary

Describe the problem and fix in 2–5 bullets:

• Problem: requestHeartbeatNow(...) exists in core heartbeat infra but is not exposed through PluginRuntime.system, forcing plugins to use /hooks/wake loopback workarounds.
• Why it matters: plugins cannot target a specific sessionKey wake in-process, and loopback wake only covers main-session behavior.
• What changed: added requestHeartbeatNow to plugin runtime system surface (runtime implementation + runtime types), and added runtime test coverage.
• What did NOT change (scope boundary): no heartbeat scheduling semantics changed; no change to /hooks/wake behavior; no routing logic changes.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes Expose requestHeartbeatNow in plugin runtime API #31564
• Related CI(main): required checks failing due to baseline regressions (install-smoke + tsgo/check) #31511

User-visible / Behavior Changes

• Plugin authors can now call runtime.system.requestHeartbeatNow({ reason, sessionKey, agentId, coalesceMs }) directly.

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 22 + pnpm
• Model/provider: N/A
• Integration/channel (if any): plugin runtime
• Relevant config (redacted): N/A

Steps

1. Create plugin runtime via createPluginRuntime().
2. Call runtime.system.requestHeartbeatNow({ reason, sessionKey, agentId, coalesceMs }).
3. Verify runtime forwards args to heartbeat wake infra function.

Expected

• Runtime exposes and forwards requestHeartbeatNow unchanged.

Actual

• ✅ Runtime now exposes requestHeartbeatNow.
• ✅ Argument forwarding verified by tests.

Evidence

Attach at least one:

• Failing test/log before + passing after

• Trace/log snippets

• Screenshot/recording

• Perf numbers (if relevant)

• Updated tests:

  • src/plugins/runtime/index.test.ts
  • extensions/bluebubbles/src/monitor.test.ts (runtime mock updated for new required system field)

• Ran:

  • pnpm test src/plugins/runtime/index.test.ts extensions/bluebubbles/src/monitor.test.ts
  • pnpm format
  • pnpm check (fails in unrelated pre-existing files)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • runtime includes system.requestHeartbeatNow
  • call forwarding preserves full options object
• Edge cases checked:
  • downstream typed runtime mocks updated where strict PluginRuntime objects are built
• What you did not verify:
  • full end-to-end plugin execution in a live gateway process

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps:

Failure Recovery (if this breaks)

• How to disable/revert this change quickly:
  • revert this PR commit
• Files/config to restore:
  • src/plugins/runtime/index.ts
  • src/plugins/runtime/types.ts
• Known bad symptoms reviewers should watch for:
  • plugin runtime type mismatches in tests/extensions that build strict PluginRuntime mocks

Risks and Mitigations

List only real risks for this PR. Add/remove entries as needed. If none, write None.

• Risk: extending PluginRuntime.system can break strict mock objects in tests/extensions.
  • Mitigation: updated strict runtime mock in BlueBubbles test and added runtime exposure test.