You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
feat(agent-core-v2): enforce telemetry domain coverage in the event registry - #3393
No linked issue — internal telemetry governance follow-up.
Problem
agent-core-v2's telemetry is governed only for what is emitted: track2 checks every event against the telemetryEventDefinitions registry at compile time. But nothing governs what should be emitted — whether a source domain records anything at all relies on author discipline. A full audit of the ~130 domains under src/ found 44 emit nothing (silent-degradation paths, security decision points, execution paths that bypass tool_call, and experiment features with no adoption signal), and there was no mechanism to even notice when a newly added domain skipped the telemetry decision.
What changed
Turns the event registry into a coverage map so the per-domain telemetry decision is structurally enforced instead of conventional:
Every registered event in events.ts now declares its owning domain — a src/ directory path (agent/loop, wire) or the pseudo-domain host for events the host app emits (first_launch, exit). The field is required by TelemetryEventMeta, so new events cannot register without it.
New src/app/telemetry/coverage.ts: telemetryDomainExemptions records the domains that intentionally emit nothing, with a reason each; telemetryDomainKnownGaps records the domains with zero coverage today, with the planned events each — the audit's gap list becomes checked-in, trackable data instead of chat history.
test/app/telemetry/events.test.ts now walks src/ and fails unless every domain owns an event, is exempted, or is a known gap. It also validates that referenced domains exist, that exemptions and known gaps are disjoint, and that reasons are non-empty. Adding a domain without making the telemetry decision now breaks the test.
Docs: the Telemetry section of packages/agent-core-v2/AGENTS.md and the agent-core-dev skill's telemetry topic describe the convention; also fixed a stale "no production bootstrap wired yet" note (kap-server, run-v2-print, and node-sdk all wire appenders today).
The mechanism already proved itself on first run: it flagged agent/modeMutex, a domain added after the initial audit, which is now exempted with a reason.
Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.
This PR includes no changesets
When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Related Issue
No linked issue — internal telemetry governance follow-up.
Problem
agent-core-v2's telemetry is governed only for what is emitted:track2checks every event against thetelemetryEventDefinitionsregistry at compile time. But nothing governs what should be emitted — whether a source domain records anything at all relies on author discipline. A full audit of the ~130 domains undersrc/found 44 emit nothing (silent-degradation paths, security decision points, execution paths that bypasstool_call, and experiment features with no adoption signal), and there was no mechanism to even notice when a newly added domain skipped the telemetry decision.What changed
Turns the event registry into a coverage map so the per-domain telemetry decision is structurally enforced instead of conventional:
events.tsnow declares its owningdomain— asrc/directory path (agent/loop,wire) or the pseudo-domainhostfor events the host app emits (first_launch,exit). The field is required byTelemetryEventMeta, so new events cannot register without it.src/app/telemetry/coverage.ts:telemetryDomainExemptionsrecords the domains that intentionally emit nothing, with a reason each;telemetryDomainKnownGapsrecords the domains with zero coverage today, with the planned events each — the audit's gap list becomes checked-in, trackable data instead of chat history.test/app/telemetry/events.test.tsnow walkssrc/and fails unless every domain owns an event, is exempted, or is a known gap. It also validates that referenced domains exist, that exemptions and known gaps are disjoint, and that reasons are non-empty. Adding a domain without making the telemetry decision now breaks the test.packages/agent-core-v2/AGENTS.mdand the agent-core-dev skill's telemetry topic describe the convention; also fixed a stale "no production bootstrap wired yet" note (kap-server, run-v2-print, and node-sdk all wire appenders today).The mechanism already proved itself on first run: it flagged
agent/modeMutex, a domain added after the initial audit, which is now exempted with a reason.Checklist
gen-changesetsskill, or this PR needs no changeset. (No changeset: registry metadata, tests, and docs are not user-perceivable.)gen-docsskill, or this PR needs no doc update. (No user-facing behavior change; engine contributor docs updated in-repo.)