Skip to content

feat: add provider-neutral telemetry contract - #26

Merged
samtay32 merged 2 commits into
mainfrom
codex/telemetry-contract
Jul 28, 2026
Merged

feat: add provider-neutral telemetry contract#26
samtay32 merged 2 commits into
mainfrom
codex/telemetry-contract

Conversation

@samtay32

@samtay32 samtay32 commented Jul 28, 2026

Copy link
Copy Markdown
Owner

Summary

  • add an optional, provider-neutral project telemetry capability that defaults to no provider
  • keep telemetry read-only, bounded, advisory, and backed by repository fallback
  • add guided onboarding, doctor/capabilities visibility, an agent skill, documentation, and behavioral activation evidence
  • explicitly prohibit Ultimate Agent Stack phone-home telemetry and implicit instrumentation/provider setup

Lock-in boundary

  • repository evidence remains authoritative
  • no telemetry provider is required
  • multiple reviewed providers may coexist by role
  • removing a provider leaves the delivery flow functional
  • provider mutations, raw payload storage, and telemetry-authorized code/deploy/release actions are forbidden

Verification

  • npm run release:check — 105 tests, behavioral contracts, package dry-run, packed smoke
  • npx --yes markdownlint-cli2@0.20.0 '**/*.md' '#node_modules' — 54 files, 0 errors
  • git diff --check

Summary by CodeRabbit

  • New Features
    • Added optional, provider-neutral project telemetry support for scoped, read-only delivery evidence.
    • Added a dedicated telemetry workflow for bounded observations validated against repository and deployment evidence.
    • Added telemetry capability reporting, setup guidance, configuration migration, and diagnostics.
  • Documentation
    • Expanded guides and policies to document telemetry boundaries, privacy protections, fallback behavior, and provider configuration.
  • Tests
    • Added coverage for telemetry defaults, validation, safety constraints, installation checks, and evaluation scenarios.

@samtay32

Copy link
Copy Markdown
Owner Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jul 28, 2026

Copy link
Copy Markdown

Review Change Stack

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 8e37b1b0-4b25-4f66-ad7e-425d522ef391

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

This change adds optional, provider-neutral project telemetry as bounded, read-only advisory evidence. It updates CLI configuration and migration, onboarding and operational guidance, a new telemetry skill and contract, packed artifacts, evaluation scenarios, and regression tests.

Changes

Project telemetry capability

Layer / File(s) Summary
Telemetry contract and invocation
.codex-plugin/plugin.json, README.md, STARTER_PROMPT.md, docs/ADAPTERS.md, skills/use-project-telemetry/*
Defines telemetry as optional, scoped, read-only evidence and adds the telemetry skill, agent interface, observation receipt contract, provider constraints, and repository validation rules.
CLI configuration and validation
bin/ultimate-agent-stack.mjs
Bumps the configuration schema to version 3, adds telemetry defaults and migration, validates provider identities and fixed safety invariants, reports telemetry capabilities, and includes telemetry in doctor, onboarding, discovery, and help output.
Onboarding and operational guardrails
assets/project-template/*, docs/ARCHITECTURE.md, docs/OPERATING_MANUAL.md, docs/TRUST.md, skills/run-autonomous-delivery/SKILL.md, skills/setup-autonomous-project/SKILL.md
Adds telemetry decisions and restrictions to project handoff, autonomy, trust, architecture, operating, setup, and delivery guidance.
Scenario, packaging, and regression coverage
evals/scenarios.json, scripts/packed-smoke.mjs, test/*.mjs
Adds telemetry activation and exclusion scenarios, packed-install assertions, default and migration validation, policy checks, and updated catalog counts.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ProjectStart
  participant Config
  participant TelemetrySkill
  participant Repository
  ProjectStart->>Config: read telemetry provider identifiers
  ProjectStart->>TelemetrySkill: provide conditional telemetry guidance
  TelemetrySkill->>Config: verify configured provider and constraints
  TelemetrySkill->>Repository: validate bounded observation against repository evidence
Loading

Possibly related PRs

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly matches the main change: introducing a provider-neutral telemetry contract.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/telemetry-contract

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

@coderabbitai

coderabbitai Bot commented Jul 28, 2026

Copy link
Copy Markdown
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@assets/project-template/.agent-stack/HANDOFF.md`:
- Around line 68-71: Unify telemetry activation so it requires both a configured
scoped provider and relevant production or operational evidence. In
assets/project-template/.agent-stack/HANDOFF.md lines 68-71, remove activation
based solely on an operational-evidence request without a provider; in
assets/project-template/AGENTS.md lines 84-90, add the same production/evidence
relevance requirement alongside provider configuration. Otherwise keep work
repository-only and retain the existing read-only, bounded-reference, and
provider-unavailable fallback behavior.

In `@bin/ultimate-agent-stack.mjs`:
- Around line 1094-1105: Update migrateConfig() to validate that
config.capabilities.telemetry is a non-null object before assigning nested
defaults, replacing malformed values with a safe object while preserving valid
telemetry settings. Update commandDoctor() to guard telemetry and providers
access against non-object or missing values, allowing it to report a
configuration error rather than throw.
- Around line 345-349: Update commandConfigure() so onboarding either persists
the selected telemetry provider into capabilities.telemetry.providers, including
the corresponding validation-compatible registration, or removes the
telemetry-provider prompt if no provider should be configurable. Keep the
existing telemetry validation behavior consistent with the chosen flow and the
TELEMETRY_PROVIDERS configuration.

In `@evals/scenarios.json`:
- Around line 83-87: Add write_project_files to the read-only diagnosis
scenario’s forbidden_actions list, and include any other evaluator-recognized
project-mutation actions alongside the existing forbidden actions so the
scenario cannot modify project files before proposing a fix.

In `@test/skill-eval.test.mjs`:
- Around line 49-50: Add an independently observed direct-telemetry-diagnosis
test case near the existing scenario count assertions, rather than relying on
passingRecord()’s copied catalog fields. Verify that telemetry activation occurs
and that the expected forbidden actions are rejected, while preserving the
existing catalog and skill count assertions.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 21c7cacc-ff99-4b56-ac76-8aae0463264e

📥 Commits

Reviewing files that changed from the base of the PR and between 8750a4f and ef59204.

📒 Files selected for processing (21)
  • .codex-plugin/plugin.json
  • README.md
  • STARTER_PROMPT.md
  • assets/project-template/.agent-stack/HANDOFF.md
  • assets/project-template/.agent-stack/core-policy.json
  • assets/project-template/AGENTS.md
  • bin/ultimate-agent-stack.mjs
  • docs/ADAPTERS.md
  • docs/ARCHITECTURE.md
  • docs/OPERATING_MANUAL.md
  • docs/TRUST.md
  • evals/scenarios.json
  • scripts/packed-smoke.mjs
  • skills/run-autonomous-delivery/SKILL.md
  • skills/setup-autonomous-project/SKILL.md
  • skills/use-project-telemetry/SKILL.md
  • skills/use-project-telemetry/agents/openai.yaml
  • skills/use-project-telemetry/references/telemetry-contract.md
  • test/agent-stack.test.mjs
  • test/maintenance.test.mjs
  • test/skill-eval.test.mjs

Comment thread assets/project-template/.agent-stack/HANDOFF.md Outdated
Comment thread bin/ultimate-agent-stack.mjs
Comment thread bin/ultimate-agent-stack.mjs Outdated
Comment thread evals/scenarios.json
Comment thread test/skill-eval.test.mjs
@samtay32

Copy link
Copy Markdown
Owner Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jul 28, 2026

Copy link
Copy Markdown
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@samtay32
samtay32 marked this pull request as ready for review July 28, 2026 22:05
@samtay32
samtay32 merged commit 3bd9a22 into main Jul 28, 2026
32 checks passed
@samtay32
samtay32 deleted the codex/telemetry-contract branch July 28, 2026 22:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant