feat(otel): opt-in OpenTelemetry setup, per-agent switch and local OTLP relay

[chhhee10]

Stacked on #881 (base feat/tui-ux). Merge #881 first; then retarget this PR to main.

What changed

Opt-in OpenTelemetry setup and an opaque local OTLP relay for FailproofAI Cloud, plus optional TypeScript and Python SDK span exporters. This restack merges feat/tui-ux into feat/otel without rewriting history and ports OTEL into its new screen language and config v2.

• failproofai otel status|enable|disable|env supports Claude Code, Codex, Gemini CLI and Copilot. Help uses the same usage/options/examples renderer as feat: the TUI redesign and config v2 (agent selection end to end) #881; reports use state dots, result glyphs and fix lines. env remains unstyled shell input.
• OTEL is not part of failproofai config. It is opt-in, per agent, through failproofai otel enable <agent>. An earlier revision added an optional wizard question; it was removed in 52020af, so setup is exactly config v2's four steps.
• Config v2's agents: {selected, seen} remains the remembered tracing list. Existing collector.agents.<agent>.sessions, otel.agents, and collector.otlp settings are retained and round-trip through v2 writes, preserving backward compatibility, transcript switching and exact recovery.
• Four agent writers retain their previous behavior: reversible managed settings, one-time backups, private recovery snapshots, byte-exact restoration if otherwise unchanged, comment preservation, no local auth-header keys, and executable/extension detection before configuring Copilot.
• Loopback-only relay, raw durable spool, authenticated forwarding, bounded requests, retries/parking, partial-success reporting and fault-isolated live reload remain unchanged. No translator, hook enforcement/socket changes or /v1/events uploader behavior changes.
• instrument("otel") and public OtelSpanExporter remain optional in both SDKs: precise OTLP/JSON batches, lazy OpenTelemetry loading, zero hard runtime dependencies, and daemon delivery without a TCP listener.
• CI and supply-chain PR filters now include the stacked base, so retargeting does not silently skip required checks. No feature-branch push/release triggers added.
• feat: the TUI redesign and config v2 (agent selection end to end) #881's Rust task-list/count assertions now explicitly include OTEL's additive SDK delivery infrastructure. Selection, backfill and agent-table production code are unchanged.

Why / dependency

OTEL is additive, opt-in and off by default. Cloud owns translation.

Paired server PR: https://github.com/FailproofAI/agenteye/pull/1062 — server merges/deploys FIRST. Both use feat/otel; the server PR is stacked on feat/cloud-redesign.

Contract: OTLP/HTTP /v1/traces, /v1/logs, /v1/metrics; existing Bearer API key with events:add; org otel.ingest_enabled (403 when off); optional otel_ingest introspection. Missing flags remain unknown, older-server 404s are parked/retained, and metrics are acknowledged only.

Testing

• Targeted OTEL/wizard/output/config-v2/stacked-CI tests: 142 passed.
• Built CLI user check: every verb's help uses the new style; enabled Claude/Codex/Gemini locally, checked managed status and a listening relay, disabled all, and verified all three configs plus credentials byte-for-byte (SHA-256 evidence).
• Real Codex CLI 0.159.3 codex exec used a local Responses test provider; actual agent OTLP logs/traces/metrics reached the local capture server through the built daemon with correct Bearer authorization. No production keys or Cloud ingestion used. The relay works even with agents.selected: [].
• Real built-CLI wizard in a PTY (before 52020af removed the OTEL question): Cloud-key field → traced-agent picker; Esc exits 0 with unchanged config. The container has no systemd, so only service discovery is stubbed; daemon, warm-worker health probe and all CLI prompts are real.
• TypeScript SDK: 552 passed; typecheck, lint and dual ESM/CJS build passed.
• Python SDK: 1081 passed, 6 skipped with optional OpenTelemetry installed.
• CLI E2E: 353 passed, 6 skipped.
• Lint: passed with the same five existing warnings; TypeScript: passed.
• Collector: cargo test -p fpai-collect passed, including config v2 + legacy OTEL compatibility.
• CLI, worker and public bundles built successfully; 1063 MDX pages validated.
• Full unit suite: 406 files passed, 8365 tests passed, 10 skipped. Initial timing-only failures under concurrent builds passed in an isolated 572-test rerun and in the full rerun; no thresholds or assertions were relaxed.
• cargo test -p failproofaid and cargo test --workspace passed, including all 8 config-v2 agent-selection E2E tests, all 7 unchanged collector-reload E2E tests, and all 3 OTLP relay E2E tests. cargo fmt --check and cargo clippy --workspace --all-targets -- -D warnings passed.
• Full bun run build passed; final E2E rerun passed 353 tests, 6 skipped; final typecheck and lint passed (the same five existing warnings).
• Audit cache fingerprints from base and restacked CLI bundles are identical under the same local toolchain (baa504718dc9ad41 / 17eef7ee76c4c1fd); evidence in tui-base-fingerprint.log and restack-audit-fingerprint.log.
• Final-head CI is GREEN at 76a749fd: all 35 checks passed, including the full CI workflow, supply-chain scan, real SDK integration shards and all four daemon platform builds. First new-base CI also passed at e5870a74. PR remains draft.
• Mintlify build validation passed. mint broken-links reports the existing 266 links in translated README files (README/license/contributing references), not the OTEL reference page; those translated README files are unchanged by this restack.
• Docker intentionally not used for this restack, as requested.

Evidence: /job/artifacts/restack-user-transcript.log, restack-user-capture.jsonl, restack-user-daemon.log, restack-wizard-pty.log, restack-restoration.json, and suite logs.

Integration notes

Stacking replaces the old integration-time UX conflict. The merge commit preserves both branch histories. OTEL uses #881's new structure, instead of restoring its old wizard/help screens.

Restack-specific shared files:

• bin/failproofai.mjs — OTEL index/help/report dispatch in the new kit.
• src/hooks/configure-wizard.ts — no OTEL step; identical to feat: the TUI redesign and config v2 (agent selection end to end) #881's four-step flow apart from comments. A test pins that no setup mode asks about or enables OTEL.
• src/hooks/fp-config.ts — documents the existing OTEL transcript overrides as orthogonal to v2 selection; reader/writer compatibility verified.
• __tests__/hooks/configure-wizard.test.ts, __tests__/hooks/otel.test.ts — setup never asks about or enables OTEL (typed/unattended/token/oss/saved); VS Code detection tests stub vscodeProbe.appPaths, so they pass on machines with VS Code installed.
• crates/failproofaid/src/main.rs, crates/failproofaid/tests/agent_selection_e2e.rs — update task expectations only for additive OTLP delivery.
• crates/fpai-collect/tests/config.rs — v2 selection/legacy transport compatibility test.
• .github/workflows/ci.yml, .github/workflows/osv-scanner.yml — include the stacked PR base, without changing release behavior.
• docs/reference/otel.mdx, CHANGELOG.md — document the new home and retain both features' release notes.

Other shared files in the full OTEL slice (relative to #881):

• src/hooks/integrations.ts, collector-config.ts, fp-home.ts, cloud-introspect.ts, safe-config-write.ts — safe JSON reader, additive settings/paths, optional introspection and credential modes.
• crates/failproofaid/src/main.rs, crates/fpai-collect/src/{config,lib}.rs, crates/fpai-collect/Cargo.toml, Cargo.lock — additive relay/transcript registration and dependencies.
• sdk/typescript/src/{index,edge/index,integrations/index}.ts, sdk/python/failproofai_sdk/{__init__,integrations/__init__}.py — optional exporter facades/registries.
• package.json, bun.lock, SDK manifests/locks — parser dependencies, dev-only OTEL test libraries and retained prior security fixes.
• docs/docs.json, docs/reference/{failproof-cli,custom-agents,custom-agents-typescript}.mdx, SDK READMEs/docs index — public feature documentation.
• Existing path/adapter-registry/SDK docs/packaging tests cover intentional additions; daemon-download fixture stages the host arch.
• sdk/typescript/integration/ai.test.ts retains the prior provider-ownership assertion for optional OTEL test libraries.
• __tests__/dashboard/jev-activity-row.test.tsx retains the prior initial-filter-refetch synchronization. No dashboard product changes.

OTEL-specific modules remain isolated: src/hooks/otel-{cli,writers,output}.ts, crates/fpai-collect/src/otlp.rs, SDK exporters and dedicated tests/docs.

Open questions

None for the client restack. Server merge/deploy precedes client; #881 must merge before this PR is retargeted to main. Existing provider registration/root Codex assignment limitations are unchanged. No publishing, merging or readiness changes performed.

[github-actions]

Thanks @chhhee10 for your contribution to Failproof AI! 🙌

We'd love to discuss your PR and welcome you to our community.

Discord: https://discord.befailproof.ai/
Reddit: https://www.reddit.com/r/failproofai/

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​jsonc-parser@​3.3.1
	npm/​smol-toml@​1.9.1
	cargo/​axum@​0.8.9
	npm/​@​opentelemetry/​sdk-trace-base@​2.12.0

View full report