elizaos--eliza/plugins/plugin-health/README.md

@elizaos/plugin-health

Owns the health, sleep, circadian-regularity, and screen-time domain for elizaOS. Extracted from @elizaos/plugin-personal-assistant so the same domain can serve other apps without bringing the LifeOps runtime along.

What this plugin owns

Connectors

Six connector contributions registered against the LifeOps ConnectorRegistry:

• apple_health
• google_fit
• strava
• fitbit
• withings
• oura

src/connectors/index.ts registers the ConnectorContributions. The Wave-1 registry adapter returns typed disconnected / transport-error results while the concrete OAuth pair/disconnect, credential storage, and provider readers live under src/health-bridge/.

Anchors

Four anchors registered against the AnchorRegistry:

• wake.observed
• wake.confirmed
• bedtime.target
• nap.start

Anchors back the relative_to_anchor trigger on ScheduledTasks — for example, the wake-up pack fires relative_to_anchor("wake.confirmed", 0) and the sleep-recap pack fires relative_to_anchor("wake.confirmed", 240).

Bus families

Eight families registered against the BusFamilyRegistry (runtime.busFamilyRegistry) and published on the ActivitySignalBus:

• health.sleep.detected
• health.sleep.ended
• health.wake.observed
• health.wake.confirmed
• health.nap.detected
• health.bedtime.imminent
• health.regularity.changed
• health.workout.completed

Default packs

• bedtime — fires before the user's target bedtime.
• wake-up — fires when wake is observed/confirmed.
• sleep-recap — recap after sleep ends.

Each pack is a ScheduledTask (or set thereof) consuming the LifeOps spine. registerHealthDefaultPacks(runtime) registers all three packs whenever the runtime exposes a defaultPackRegistry; if it is absent the plugin logs a single skip line and contributes nothing.

Domain logic

• src/sleep/ — sleep / circadian / regularity engines.
• src/screen-time/ — type-only exports (LifeOpsScreenTimePerAppUsage, LifeOpsScreenTimeSummaryPayload); the aggregator lives in plugins/plugin-personal-assistant/src/lifeops/service-mixin-screentime.ts pending Wave-2 (W2-D) decoupling.
• src/health-bridge/ — detectHealthBackend (HealthKit on darwin, Google Fit REST fallback), the Strava/Fitbit/Withings/Oura OAuth-bridged readers, the per-provider OAuth flow, and the createLifeOpsHealth* record factories. These are direct function exports, not HTTP routes.

How LifeOps consumes plugin-health

LifeOps does not import internal modules. Consumption goes through:

1. Connector contributions — registered into LifeOps's ConnectorRegistry at boot via registerHealthConnectors(runtime).
2. Anchor contributions — registered via registerHealthAnchors(runtime) into the AnchorRegistry.
3. Bus families — registered via registerHealthBusFamilies(runtime) into BusFamilyRegistry (runtime.busFamilyRegistry).
4. Default packs — registered via registerHealthDefaultPacks(runtime).
5. Public exports — detectHealthBackend, sleep utilities, screen-time helpers exported from @elizaos/plugin-health and re-exported by @elizaos/plugin-personal-assistant only where the surface is part of the LifeOps public API.

If the LifeOps runtime registries are not available at boot, the plugin logs a single skip line and contributes nothing. This is the soft-dependency posture.

Soft-dependency posture

plugin-health does not require @elizaos/plugin-personal-assistant. Other apps can consume the plugin by registering their own implementations of:

• ConnectorRegistry (with register / list / get / byCapability)
• AnchorRegistry (with register / list / get)
• BusFamilyRegistry (with register / list)
• DefaultPackRegistry (with register / list / get)

The structural contracts the plugin builds against live in src/connectors/contract-types.ts, src/default-packs/contract-types.ts, and src/contracts/health.ts.

Where to look next

• Plugin entry: src/index.ts.
• LifeOps consumption: plugins/plugin-personal-assistant/README.md.
• Frozen contracts: see plugins/plugin-personal-assistant/AGENTS.md for the connector / channel / transport contracts this plugin implements.