Module telemetry 

Lifecycle telemetry readers.

Lifeloop owns lifecycle-relevant telemetry parsing for harness adapters. Clients (CCD, RLM, and other lifecycle clients) consume neutral PressureObservation snapshots instead of writing per-harness log readers themselves.

Boundary (issue #5)

This module owns:

• parsing harness-native session/telemetry artifacts into a neutral PressureObservation (adapter id, observed time, model name, token counts, context window, compaction signal),
• the env-var resolution rules used to locate those artifacts and to override their parsed values (with LIFELOOP_* aliases winning over the compatibility CCD_* inputs),
• a neutral telemetry TelemetryError type whose variants name the lifecycle failure classes (telemetry_unavailable, hook_protocol_error, internal_error).

This module does not own:

• receipt emission (callers translate TelemetryError into a crate::LifecycleReceipt),
• the placement/payload pipeline (issue #4 owns asset rendering),
• adapter manifest registration (issue #6 owns the manifest registry — this module merely reports support states the registry can attach to a context_pressure claim),
• the hook protocol command strings (issue #3),
• lifecycle routing (issue #7),
• any client-side state, prompt semantics, or continuity vocabulary. Specifically: no memory, recall, promotion, compaction policy, radar, or governance reasoning. Lifeloop reports the signal; clients decide what it means.

CCD compatibility

Existing CCD_* env vars (e.g. CCD_CLAUDE_HOME, CCD_CONTEXT_WINDOW_TOKENS, CCD_HOST_MODEL) are honored as compatibility inputs through lifeloop.v0.x. Each has a LIFELOOP_* alias; when both are set, the LIFELOOP_* value wins and a single bounded warning is recorded per resolved key per process. Removal criteria are tracked in docs/tombstones/lifeloop.v0.md.

Modules

claude

Claude Code lifecycle telemetry reader.

codex

Codex CLI lifecycle telemetry reader.

gemini

Gemini CLI lifecycle telemetry reader.

host

Host-adapter dispatch and shared env aliases for telemetry readers.

opencode

OpenCode lifecycle telemetry reader.

Structs

EnvAlias

A single CCD→Lifeloop env-var alias.

EnvPrecedenceWarning

Bounded warning emitted once per resolved alias when both LIFELOOP_* and CCD_* are set. The lifeloop value wins; the ccd_compat value is shadowed.

EnvWarningSink

Sink for env-precedence warnings.

PressureObservation

A neutral lifecycle-pressure observation extracted from harness telemetry. Carries everything a context.pressure_observed event or a receipt telemetry_summary needs, with no harness-private fields.

TokenUsage

Per-side token usage breakdown. All fields default to zero so the type stays format-agnostic for Deserialize.

Enums

TelemetryError

Telemetry-side errors. The variants name the failure classes the spec uses for telemetry-derived receipts:

Constants

GENERAL_CONTEXT_WINDOW_ALIASES

Lifeloop/CCD general context-window fallback. Adapter readers should consult their adapter-specific alias first, then fall back to this. The general fallback exists so users with custom or local setups don’t have to set a runtime-prefixed env var.

GENERAL_HOST_MODEL_ALIASES

Generic host-model fallback used by every adapter when a more specific alias does not resolve.

RECENT_ACTIVITY_SECS

Default recency window (seconds) for considering a telemetry artifact fresh enough to drive a context.pressure_observed event. Mirrors the 30-minute threshold the CCD readers used.

Functions

as_u64

Coerce a JSON value to u64, accepting both numbers and parseable strings.

compute_pct

env_warning_sink

Process-wide warning sink used by resolve_env_string and resolve_env_u64. Callers can drain to surface these warnings on their preferred channel.

file_mtime_epoch_s

Seconds since UNIX epoch for the file’s mtime, or None if the file is missing.

general_context_window

general_host_model

home_dir

is_recent

now_epoch_s

number_key

Recursively search a JSON value for the first matching numeric value by candidate key names. Accepts both JSON numbers and stringified integers.

resolve_env_string

Resolve an env-var string through the alias list. The first alias whose lifeloop key is set wins; otherwise the first alias whose ccd_compat key is set wins. Whenever an alias has both sides set, a precedence warning is recorded (once per lifeloop key per process) regardless of which alias actually carried the resolution.

resolve_env_string_with

Like resolve_env_string but reads through a closure (for tests that don’t want to mutate process env).

resolve_env_u64

Resolve an env alias as u64, parsing the string form.

string_key

Recursively search a JSON value for the first matching string by candidate key names. Descends into objects and arrays depth-first.

Type Aliases

TelemetryResult