Skip to content

Stop heartbeat tool turns from asking for HEARTBEAT_OK#76338

Merged
pashpashpash merged 2 commits intomainfrom
codex/heartbeat-tool-no-ok
May 3, 2026
Merged

Stop heartbeat tool turns from asking for HEARTBEAT_OK#76338
pashpashpash merged 2 commits intomainfrom
codex/heartbeat-tool-no-ok

Conversation

@pashpashpash
Copy link
Copy Markdown
Contributor

@pashpashpash pashpashpash commented May 3, 2026

Heartbeat turns now have two reply contracts. The legacy text path still needs HEARTBEAT_OK so OpenClaw can treat a quiet heartbeat as no user-visible reply, but Codex runtime/message-tool turns have the structured heartbeat_respond tool where silence is represented with notify=false.

Before this change, the Codex happy path could receive both instructions in the same heartbeat turn: use the heartbeat tool, and also reply HEARTBEAT_OK when nothing needs attention. That is exactly the kind of mixed contract that makes the model second-guess the tool path.

This keeps HEARTBEAT_OK for explicit automatic reply mode, but rewrites heartbeat prompts for message-tool and Codex harness sessions so they point at heartbeat_respond instead. The happy-path heartbeat snapshot now shows the structured tool contract without the old text sentinel.

While chasing that cleanup, we also removed the old runtime fallback surface instead of preserving a silent downgrade path. Explicit runtime selection is now honest: asking for Codex, Claude CLI, or another plugin runtime either selects that runtime or fails clearly. The remaining compatibility behavior is agentRuntime.id: "auto", where OpenClaw can still use PI when no plugin harness claims a run. Legacy agentRuntime.fallback config is cleaned up through doctor, and the schema, generated config metadata, status metadata, docs, and tests now match that contract.

@openclaw-barnacle openclaw-barnacle Bot added size: M maintainer Maintainer-authored PR labels May 3, 2026
@clawsweeper
Copy link
Copy Markdown
Contributor

clawsweeper Bot commented May 3, 2026

Codex review: needs maintainer review before merge.

Summary
The PR rewrites heartbeat prompts for structured heartbeat_respond turns and removes the agent runtime fallback config/env/docs/schema surface so explicit plugin runtimes fail closed.

Reproducibility: yes. by source inspection. Current main combines the default HEARTBEAT_OK heartbeat prompt with appended heartbeat_respond guidance, and Codex heartbeat turns force the structured tool.

Next step before merge
The remaining blocker is maintainer approval for a protected-label PR that removes a public compatibility policy surface; no narrow automated repair is indicated after the latest branch update.

Security
Cleared: The diff touches prompts, runtime selection, config schemas, docs, tests, and generated metadata; no concrete security or supply-chain issue was found.

Review details

Best possible solution:

Land the heartbeat prompt split once maintainers approve the runtime fallback policy change, or split the fallback removal into a separate policy PR and land the narrower heartbeat fix first.

Do we have a high-confidence way to reproduce the issue?

Yes, by source inspection. Current main combines the default HEARTBEAT_OK heartbeat prompt with appended heartbeat_respond guidance, and Codex heartbeat turns force the structured tool.

Is this the best way to solve the issue?

Unclear as a product decision. The heartbeat prompt split is the narrow fix, but retiring the public fallback config/env surface is a broader compatibility change that should be explicitly accepted by maintainers.

What I checked:

  • Current main mixes heartbeat contracts: The default heartbeat prompt still asks quiet turns to reply HEARTBEAT_OK, while the runner appends heartbeat_respond tool guidance before dispatching the heartbeat turn. (src/auto-reply/heartbeat.ts:14, dda2cf4e73b3)
  • Codex heartbeat turns force the structured tool: The Codex app-server runtime enables and forces the heartbeat response tool when the trigger is heartbeat, making the mixed text/tool prompt observable for Codex heartbeat turns on current main. (extensions/codex/src/app-server/run-attempt.ts:1485, dda2cf4e73b3)
  • PR head uses the tool-mode heartbeat prompt: At the PR head, resolveHeartbeatPromptForResponseTool creates a heartbeat_respond/notify=false prompt without the default HEARTBEAT_OK sentinel, and resolveHeartbeatRunPrompt selects it for message-tool/Codex heartbeat paths. (src/auto-reply/heartbeat.ts:17, ca20f880f6aa)
  • Runtime fallback removal is an intentional branch behavior: The PR head changes missing explicit plugin harness selection to throw immediately, removes fallback from the runtime zod schema, and adds doctor migration logic to remove legacy agentRuntime.fallback. (src/agents/harness/selection.ts:114, ca20f880f6aa)
  • Protected maintainer label and clean PR state: GitHub's pull request API reports the PR is open, non-draft, mergeable clean, and labeled maintainer; exact-head check runs for ca20f880f6aa413dff66c5e7b4f596b5a7cfb758 are completed successfully aside from expected skipped/neutral jobs. (ca20f880f6aa)

Likely related people:

  • pashpashpash: Local blame and GitHub path history tie current heartbeat prompt/tool and explicit harness-failure behavior to recent merged commits by this handle, including structured heartbeat responses and explicit harness failure work. (role: introduced relevant heartbeat/runtime behavior and PR author with prior merged history; confidence: high; commits: 439d8edf68e2, 11804a484ded; files: src/infra/heartbeat-runner.ts, src/auto-reply/heartbeat.ts, src/agents/harness/selection.ts)
  • steipete: GitHub path history shows recent commits by this handle in heartbeat runner scheduling/routing, agent runtime config migration, and Codex harness selection. (role: recent maintainer for heartbeat, runtime config, and Codex harness areas; confidence: medium; commits: 5b9be2cdb1c0, 47c0ce5f8531; files: src/infra/heartbeat-runner.ts, src/agents/harness/selection.ts, extensions/codex/harness.ts)
  • vincentkoc: Recent runtime-selection history includes provider/runtime normalization work by this handle, and the PR timeline explicitly requested review from this handle. (role: adjacent runtime selection maintainer; confidence: medium; commits: aa27e27f3606; files: src/agents/harness/selection.ts)

Remaining risk / open question:

  • The PR removes the public agentRuntime.fallback and OPENCLAW_AGENT_HARNESS_FALLBACK compatibility surface; that is intentional in the discussion but still needs maintainer approval because existing configs may rely on it.

Codex review notes: model gpt-5.5, reasoning high; reviewed against dda2cf4e73b3.

@pashpashpash pashpashpash force-pushed the codex/heartbeat-tool-no-ok branch 3 times, most recently from 2ec5f57 to 451c1ff Compare May 3, 2026 01:25
@pashpashpash pashpashpash force-pushed the codex/heartbeat-tool-no-ok branch from 451c1ff to 78ed1be Compare May 3, 2026 01:36
@openclaw-barnacle openclaw-barnacle Bot added agents Agent runtime and tooling size: L and removed size: M labels May 3, 2026
@pashpashpash pashpashpash force-pushed the codex/heartbeat-tool-no-ok branch from 78ed1be to 2875b4a Compare May 3, 2026 01:43
@openclaw-barnacle openclaw-barnacle Bot added the gateway Gateway runtime label May 3, 2026
@pashpashpash pashpashpash force-pushed the codex/heartbeat-tool-no-ok branch from 2875b4a to f7a4803 Compare May 3, 2026 01:46
@pashpashpash pashpashpash requested a review from a team as a code owner May 3, 2026 02:20
@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation commands Command implementations size: XL and removed size: L labels May 3, 2026
@pashpashpash pashpashpash force-pushed the codex/heartbeat-tool-no-ok branch from 8cb5cb8 to ca20f88 Compare May 3, 2026 02:27
@pashpashpash
Copy link
Copy Markdown
Contributor Author

ClawSweeper's fallback-compatibility finding is intentionally not being applied here.

Pash explicitly asked in this PR to remove the silent runtime fallback and make explicit runtime selection fail honestly. The current branch now removes the agentRuntime.fallback and OPENCLAW_AGENT_HARNESS_FALLBACK public config/env surface, migrates legacy agentRuntime.fallback entries out through doctor, updates docs/schema/metadata/tests, and keeps auto as the explicit compatibility mode that may use PI when no plugin harness claims a run.

So the behavior is now deliberately:

  • agentRuntime.id: "codex" means Codex, or a clear failure if Codex is unavailable.
  • agentRuntime.id: "auto" means plugin auto-selection, with PI available when no plugin harness claims the run.
  • there is no opt-in silent PI fallback for explicit plugin runtimes.

Local validation passed after rebasing on current main, and exact-head CI is green for ca20f880f6aa413dff66c5e7b4f596b5a7cfb758.

@pashpashpash pashpashpash merged commit 8f4eaa9 into main May 3, 2026
107 checks passed
@pashpashpash pashpashpash deleted the codex/heartbeat-tool-no-ok branch May 3, 2026 04:46
lxe pushed a commit to lxe/openclaw that referenced this pull request May 6, 2026
* fix heartbeat tool prompt sentinel

* fix: remove agent runtime fallback config
github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request May 9, 2026
* fix heartbeat tool prompt sentinel

* fix: remove agent runtime fallback config
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agents Agent runtime and tooling commands Command implementations docs Improvements or additions to documentation gateway Gateway runtime maintainer Maintainer-authored PR size: XL

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant