#12917: feat(gateway): add agents.health RPC method for per-agent health over…
gateway
stale
…view
Adds a new `agents.health` gateway RPC method that aggregates existing data from agents.list, sessions, and cron into a single per-agent health summary. Useful for dashboard rendering and CLI health checks.
Each agent entry includes:
- status (healthy/warning/error/unknown) with reason
- main session info (model, tokens, last activity)
- active session count
- cron summary (total, enabled, failing, next run, last failure)
Status is derived automatically:
- warning: cron jobs failing or main session idle >30m
- unknown: no sessions and no cron jobs
- healthy: everything nominal
Registered as a read-scope method, available in the control UI and via WebSocket RPC.
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR adds a new gateway RPC method `agents.health`, registers it in the gateway method list, and grants it read-scope access. The new handler aggregates agent metadata, session store entries, and cron jobs into a per-agent health summary (status + reason, main session info, active session count, cron summary) intended for dashboards/CLI.
The overall approach fits the gateway’s existing “server-methods” pattern by adding a dedicated handler module and wiring it into `coreGatewayHandlers` alongside existing `agents.*`/`cron.*` methods.
<h3>Confidence Score: 2/5</h3>
- Not safe to merge as-is due to a definite runtime bug in cron aggregation for `agents.health`.
- `agents.health` calls `context.cron.list` and treats its return value as an array, but the established contract returns an object `{ jobs }` (per existing `cron.list` handler). This will break cron grouping/status derivation at runtime, and the accompanying test currently mocks the wrong shape so it won’t catch the issue.
- src/gateway/server-methods/agents-health.ts, src/gateway/server-methods/agents-health.test.ts
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#21612: feat(gateway): add ops runtime summary API
by frank8ai · 2026-02-20
75.8%
#7128: feat: add gateway.restart RPC for graceful in-process restart
by AkashaBot · 2026-02-02
73.6%
#13537: Gateway: add commands.list slash command metadata API
by Pyiner · 2026-02-10
73.2%
#14618: feat(ui): add AgentHQ - agent workspace evolution viewer
by eddie333016 · 2026-02-12
73.0%
#6515: fix: in-process IPC for cron tool to avoid WS self-contention timeout
by amco3008 · 2026-02-01
72.7%
#11788: feat: inter-agent communication via CLI scripts
by jingkang0822 · 2026-02-08
72.5%
#10748: feat: Add sessions.spawn gateway method for direct subagent spawning
by fox-openclaw · 2026-02-06
72.4%
#8522: feat(control-ui): Add Model Requests panel for real-time API monito...
by GiantAxeWhy · 2026-02-04
72.3%
#8713: feat: gateway memory monitor, install linger, docs and failover
by quratus · 2026-02-04
72.1%
#6512: Claude/setup open claw agent f v sqk
by franelcisco · 2026-02-01
72.0%