@mosaicstack/comms (0.0.2-next.2680)

Published 2026-08-25 18:55:51 +00:00 by woodpecker in mosaicstack/stack

Set up this registry in your project .npmrc file:

@mosaicstack:registry=https://git.mosaicstack.dev/api/packages/mosaicstack/npm/

To install the package using npm, run the following command:

npm install @mosaicstack/[email protected]

or add it to the package.json file:

"@mosaicstack/comms": "0.0.2-next.2680"

For more information on the npm registry, see the documentation.

MACP presence SDK — the **P1 (presence)** slice of RFC-001 (§4.5 liveness, §4.2 event envelope). Minimal by design: set Matrix presence, run the `mosaic.presence` heartbeat, and compute **deterministic** fleet liveness.

@mosaicstack/comms

MACP presence SDK — the P1 (presence) slice of RFC-001 (§4.5 liveness, §4.2 event envelope). Minimal by design: set Matrix presence, run the mosaic.presence heartbeat, and compute deterministic fleet liveness.

Out of P1 scope (later phases): enrollment/auto-detect, room taxonomy, per-agent token minting, signed-authorship, federation.

API

classifyLiveness(ageMs, policy) / computeFleetLiveness(observations, now, policy) — pure, deterministic online/away/offline from heartbeat age. The authoritative liveness source (RFC-001 §4.5): native Matrix presence is not relied upon.
HeartbeatEmitter / startHeartbeatLoop(...) — build and drive the mosaic.presence heartbeat (monotonic seq, interval_ms).
MinimalMatrixClient — tiny C-S client: setPresence, sendHeartbeat, readHeartbeats, joinRoom. Supports Application-Service masquerade (actAsUserId) for the P1 provisioner, or a per-agent accessToken.
PresenceAgent — high-level: join the fleet room, go present, heartbeat. pauseHeartbeat() models a crash (no graceful signal).
FleetLivenessReader — reads the fleet room and computes the liveness board (read() / formatBoard()), the surface a human or watchdog reads.

Liveness policy (RFC-001 §4.5)

online : age <= heartbeatIntervalMs * missTolerance
away   : age <  darkThresholdMs
offline: otherwise (or never-seen / non-finite age -> fail safe to offline)

Defaults: interval 30s, miss-tolerance 2, dark-threshold 10min (DEFAULT_LIVENESS_POLICY). All runtime-tunable per RFC-002 §5.3.

Tests

pnpm --filter @mosaicstack/comms test — the liveness core is written RED-FIRST; an end-to-end proof against a real Synapse lives in tools/matrix-presence-harness.

Development Dependencies