Integration

Federated Heartbeat

Name: Federated Heartbeat
Rating: 3.5 (1 reviews)
Author: ncurado

By ncurado 👁 4 views ▲ 0 votes

Federated heartbeat mesh plugin for OpenClaw - coordinates staggered heartbeats across pilot agents to reduce API rate limiting

GitHub

Configuration Example

{
  "tickIntervalMs": 30000,
  "claimTtlMs": 60000,
  "meshModulo": 20,
  "meshEpoch": "2026-03-04T00:00:00Z",
  "enforceChannelIds": ["discord", "slack"]
}

README

# Federated Heartbeat Mesh (OpenClaw Plugin)

A standalone OpenClaw plugin that provides:

1. **Metronome**: emits `system.tick` every 30s (configurable)
2. **Deterministic tick claiming**: each agent computes its execution slot from `sha256(agentId) % meshModulo`
3. **Thread-ownership interception hooks**: cancels duplicate responders at `message_sending`

Designed for pilot rollout with low-risk agents (`copy-editor`, `script-smith`, `oracle`, `creative-writer`, `qa`).

---

## Install

Copy or symlink this folder into your OpenClaw extensions/plugins path, then enable it in your OpenClaw config.

Example layout:

```bash
/home/ncurado/.openclaw/workspace/plugins/openclaw-federated-heartbeat/
  package.json
  index.js
  src/
  README.md
```

If your OpenClaw runtime discovers local plugins by path, point it to this directory.

---

## Configuration

This plugin uses standard plugin config (`api.pluginConfig`) with these fields:

```json
{
  "tickIntervalMs": 30000,
  "claimTtlMs": 60000,
  "meshModulo": 20,
  "meshEpoch": "2026-03-04T00:00:00Z",
  "enforceChannelIds": ["discord", "slack"]
}
```

### Field notes

- `tickIntervalMs` (default `30000`): metronome interval
- `claimTtlMs` (default `tickIntervalMs * 2`): TTL for tick/thread claims
- `meshModulo` (default `20`): number of deterministic execution slots
- `meshEpoch` (optional): stable epoch metadata
- `enforceChannelIds` (optional): if set, ownership interception only applies on these channel IDs

---

## How deterministic claiming works

For each agent:

```js
slot = sha256(agentId) % meshModulo
shouldRun = (tickSequence % meshModulo) === slot
```

Only agents whose slot matches the tick sequence should respond on that tick.

The plugin also tracks in-memory claims so if two agents attempt the same thread/send path in the same tick window, only the first claim succeeds.

---

## Lifecycle

- `register(api)` registers a long-lived service (`start`/`stop`)
- On `start()`:
  - starts metronome
  - subscribes to diagnostics stream (if runtime provides `ctx.onDiagnosticEvent`)
- On `stop()`:
  - unsubscribes
  - stops metronome
  - clears claim registries

---

## Pilot test checklist (5 low-risk agents)

1. Enable plugin for pilot agents only.
2. Verify logs show tick emission every 30 seconds.
3. Confirm each pilot agent only runs on its deterministic slot.
4. Trigger thread contention and verify duplicate sends are cancelled.
5. Observe for 24-48h before broader rollout.

---

## Notes

- Claim registries are in-memory/ephemeral by design.
- Hook behavior is **fail-open** before first tick arrives.
- This plugin is intentionally self-contained and avoids external dependencies.

integration