2e7c124e4d
All checks were successful
ci/woodpecker/pr/ci Pipeline was successful
Implements RFC-001 P1 (the first shippable slice): deterministic Matrix presence/liveness on a single-instance dev Synapse. - infra/matrix/: DEV Synapse (RFC-002 Mode B, federation OFF, self-signed TLS, enable_registration:false, appservice registration wired). Rendered from parameterized templates — zero hardcoded topology. .data is gitignored. - packages/comms/: minimal MACP presence SDK — set presence, run the mosaic.presence heartbeat (seq + interval per RFC-001 §4.5), and a deterministic liveness reader (online/away/offline from heartbeat age, NOT native-presence-timeout). Liveness core written RED-FIRST. 19 vitest tests. - tools/matrix-presence-harness/: minimal provisioner (registers >=3 agent MXIDs, creates the fleet presence room, joins them — reuses the existing @mosaicstack/appservice intent lib) + an E2E validation harness proving A2/A3/A4 against a real Synapse. - eslint.config.mjs: register packages/comms/vitest.config.ts with the type-aware project service (same as other packages' vitest configs). DEV-compose validated only; production deploy is a separate coordinated step (deploy-holds respected). Part of the comms-evolution program (RFC-001 P1) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0158NZqN2n2ymKFeJAZ4GUCb
42 lines
1.8 KiB
Markdown
42 lines
1.8 KiB
Markdown
# @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`.
|