telemetry

Imported from Bearmancer/omo-agy (packages/omo-senpi/src/components/telemetry/AGENTS.md). Install upstream with npx skills add Bearmancer/omo-agy --skill telemetry. Copyright stays with the author.

telemetry component

Senpi telemetry adapter over @oh-my-opencode/telemetry-core PostHog primitives. Two products share this directory: the legacy omo-senpi daily-active ping (index.ts) and the richer omo-native event family (everything omo-native-*). Both are anonymous, best-effort, and must never block or crash the host.

Anatomy

Event model

• Legacy product: single event omo_senpi_daily_active, reason session_start. Distinct id is sha256("omo-senpi:" + hostname) (telemetry-core machine-id.ts); once-per-UTC-day dedupe lives in the state dir.
• omo-native product: daily_active, session_started, prompt_submitted, turn_completed, skill_loaded, delegation_started, delegation_completed, category_config, feature_used, parallelism_summary. Every event is schema-declared from product-identity.ts; properties outside the allowlist do not ship. Session ids are salted sha256 hashes, salt local to the machine.
• parallelism_summary remains one event per session. V2 adds eval event-bus availability, accepted/rejected execution counts, nested status/duration totals, outer eval wrapper counts, and mixed-wave direct counts. Existing non-eval wave and savings formulas are unchanged.
• Free-form strings are masked to closed vocabularies: unknown providers/models/skills/agents become custom or are dropped. Numeric properties are bucketed where cardinality matters.

Privacy and opt-out

• Env opt-outs (telemetry-core env.ts): DO_NOT_TRACK, OMO_DISABLE_POSTHOG / OMO_SENPI_DISABLE_POSTHOG (1|true|yes), OMO_SEND_ANONYMOUS_TELEMETRY / OMO_SENPI_SEND_ANONYMOUS_TELEMETRY (0|false|no|yes). Config gate: isOmoTelemetryEnabled from omo-config-core.
• Never captured: prompt text, file paths, hostnames in clear, raw session ids, custom provider names, and custom model names (any model id outside the shipped vocabulary — fine-tunes, private deployment names, internal codenames).
• Provider and model are masked by DIFFERENT rules, and maskProviderAndModel is the single place that decides: provider is exported only when it is in KNOWN_PROVIDERS (a user-authored gateway name never leaves the machine), while model_id is exported whenever it matches ALL_KNOWN_MODEL_IDS regardless of the routing provider, because a shipped model id is a public product name. Changing this boundary means changing the published disclosure in docs/reference/senpi-telemetry.md in the same commit.
• API keys come from POSTHOG_API_KEY or the write-only defaults named in product-identity.ts / telemetry-core constants; do not duplicate key literals elsewhere.
• First-run disclosure notice is mandatory and marker-gated; it fires only when telemetry is actually enabled.

Delegation telemetry invariants

• Observer ledger. Terminal edges arrive through the shared ledger in ../task/terminal-observers.ts (globalThis + Symbol.for, one instance across re-registration), fed by the status-edge store wrapper that watches every write path (save/replace/mutate/transition), so reconciliation-written lost records are observed too. Observer callbacks are individually try/caught; a throwing observer never affects the store result or task liveness. createOmoNativeDelegationCapture subscribes at register and must unsubscribe on dispose, otherwise each session switch stacks another observer writing into a dead client.
• Session-hash ownership. Delegation events hash record.parent_session_id, the session that owns the task, and pass that hash explicitly. Only the session_start path may set state.sessionHash; a resumed old task must never redirect the live session's events by mutating shared state.
• Child-process gate. Native telemetry never emits from senpi-task child or team-member processes: components/task/index.ts returns early on isTeamMemberProcess(), and in-process children load zero extensions (child-loader.ts). This is a test-pinned invariant; a child turn must never produce a parent delegation or turn event.

Conventions

• Fire-and-forget everywhere: capture failures surface once through the diagnostics callback or debug log, never to the user, never as a thrown error.
• New events require a schema entry + allowlist in product-identity.ts, a doc regeneration (schema-doc.test.ts fails otherwise), and bucketing for any unbounded value.
• Tests inject env, now, osProvider, stateDir, and transportFactory; no test touches the network or the real agent home.

Anti-patterns

• Do not emit per-turn variants of session-scoped events (parallelism_summary is once per session by design).
• Do not fold mixed waves into non_eval or clamp negative savings; both hide measurement anomalies.
• Do not add eval-internal calls to top-level waves or infer nested concurrency/savings from aggregate duration sums; the producer event does not carry the required interval graph.
• Do not add properties outside the declared schema, log raw session ids, or widen the timeout so telemetry can delay session_start.