Improve anonymous OSS telemetry quality

[santoshkumarradha]

Summary

• version the anonymous telemetry payload and add privacy-safe idempotency keys
• normalize execution lifecycle outcomes and bounded operational dimensions
• report the control-plane build version and keep installation identity stable across local and Docker restarts
• preserve default-on telemetry with a working AGENTFIELD_TELEMETRY_ENABLED=false opt-out
• clarify the public privacy and configuration documentation

Privacy and behavior

The hosted payload remains allowlisted and excludes prompts, execution payloads, raw errors, and raw execution/workflow/node identifiers. The identifier is pseudonymous and installation-scoped rather than person-scoped.

Telemetry remains best-effort and non-blocking. This change does not alter execution state transitions, API responses, storage behavior, or agent communication.

Validation

• go test ./internal/observability ./internal/config ./internal/handlers ./cmd/agentfield-server -count=1
• Docker Compose renders telemetry enabled by default and disabled when AGENTFIELD_TELEMETRY_ENABLED=false
• git diff --check

Lifecycle classification applies to events emitted by the existing execution paths; storage-only terminal transitions remain outside this patch.

[github-actions]

📊 Coverage gate

Thresholds from .coverage-gate.toml: per-surface ≥ 84%, aggregate ≥ 85%, max per-surface regression ≤ 1.0 pp, max aggregate regression ≤ 0.50 pp.

Surface	Current	Baseline	Δ
control-plane	87.00%	87.40%	↓ -0.40 pp	🟡
sdk-go	92.50%	92.00%	↑ +0.50 pp	🟢
sdk-python	93.82%	93.73%	↑ +0.09 pp	🟢
sdk-typescript	91.05%	90.42%	↑ +0.63 pp	🟢
web-ui	84.75%	84.79%	↓ -0.04 pp	🟡
aggregate	85.58%	85.75%	↓ -0.17 pp	🟡

✅ Gate passed

No surface regressed past the allowed threshold and the aggregate stayed above the floor.

[github-actions]

📐 Patch coverage gate

Threshold: 80% on lines this PR touches vs origin/main (from .coverage-gate.toml:thresholds.min_patch).

Surface	Touched lines	Patch coverage	Status
control-plane	287	87.00%	✅
sdk-go	0	—	➖ no changes
sdk-python	0	—	➖ no changes
sdk-typescript	0	—	➖ no changes
web-ui	0	—	➖ no changes

✅ Patch gate passed

Every surface whose lines were touched by this PR has patch coverage at or above the threshold.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[AbirAbbas]

Reviewed and sanity-checked this end-to-end — looks good to merge.

Beyond the unit tests, I actually booted the server with the telemetry endpoint pointed at a local capture server and watched the wire payloads:

• control_plane_started arrives with telemetry_schema_version: 2, the real build version (previously hardcoded "unknown" — the cfg.Telemetry.AgentFieldVersion wiring works), normalized storage_mode, and only the hashed install ID. The raw install ID never appears in the serialized payload.
• AGENTFIELD_TELEMETRY_ENABLED=false → server boots healthy, zero telemetry requests sent.
• Restarting against the same AGENTFIELD_HOME produces an identical install ID hash, so installation identity is stable. The install_id_path: "" default is right — Docker gets /data/telemetry/install_id via AGENTFIELD_HOME=/data on the persistent volume, and bare-metal installs no longer try to write to a hardcoded /data they may not own.

Things I specifically went looking for and came back clean on:

• normalizeStorageMode only accepting local/postgres is correct — those are exactly the values the storage factory accepts, so nothing real gets bucketed as unknown.
• The HMAC idempotency keys line up with the publish paths: terminal completed/failed/cancelled events carry a stable key, so the duplicate controller + status-callback publishes dedupe at ingest. ExecutionUpdated-driven terminal events deliberately get random keys (timeout can recur), worst case a slight over-count in an edge path — fine for telemetry.
• Privacy is a strict improvement: raw agent version dropped, sdk_version regex-bounded, everything else allowlisted into fixed vocabularies, and the tests assert raw execution/workflow/install IDs don't leak into the encoded payload.

go build ./... clean, go test ./internal/observability ./internal/config ./internal/handlers ./cmd/agentfield-server all pass locally, changed files are gofmt-clean, CI green.