feat(mcp): expose environment usage summary

[juliusmarminge]

Agents could not query the existing environment usage service through the authenticated MCP endpoint without relying on the client Usage page.

This change adds t3_environment_usage, a current-environment read over the existing UsageService. It validates a maximum 31-day daily window or 24-hour hourly window, returns deterministic bucket pages with Unicode-safe bounded model/pricing text, and preserves token, unpriced-record, source-status, and pricing provenance.

The result is deliberately narrower than the shared usage RPC: source fingerprints, host IDs, provider-home paths, volume IDs, transcript contents, credentials, and raw failures are omitted. Costs are labeled API-equivalent estimates, missing or failed sources remain explicit, and live-summary pagination warns that later pages can shift. The explicit read may scan transcripts, refresh cached pricing, and update existing scan caches; it adds no collector or telemetry path.

Focused validation: 76 service/production-registration/adapter/presentation tests, including MCP tools/list root-object properties, 31-day and 24-hour boundaries, invalid zones, Unicode astral-character encoding, deterministic pagination, partial/failed source redaction, capability/environment denial, and finite failure mapping. Targeted lint, contracts typecheck, and vp run -F t3 typecheck pass.

Dependency: immutable rollout base agents/mcp-controls/base-490318a at 490318afa505d3d033295eca12d7e62b4b922725. This is an independent standalone PR, not a member of native environment stack #8729.

Implemented by GPT-5.6-Sol via Codex in T3 Code.

---

Note

Medium Risk
New authenticated read path can trigger transcript scans and cache refresh; redaction and validation reduce leakage risk but live pagination and usage aggregation behavior affect agent-facing data.

Overview
Adds a read-only MCP tool t3_environment_usage so agents can query aggregated usage for the authenticated environment through the existing UsageService, without going through the Usage UI.

EnvironmentUsageMcpService enforces orchestration capability and environment ID match, validates bounded windows (up to 31 calendar days at daily resolution or 24 hours at hourly resolution, IANA timezone, hourly day-label rules), then projects usage into contract types with cursor-paginated, deterministically sorted buckets, Unicode-capped model text, and fixed metadata (costMeaning, paginationConsistency, cacheBehavior). Sensitive internals are stripped: no source fingerprints, paths, raw scan errors, or pricing URLs—generic source messages and a fixed litellm_public_model_prices provenance label instead.

The toolkit is wired into McpHttpServer, t3_environment_usage is added to Claude’s read-only MCP pre-approval list (with tests covering orchestrator + environment usage readonly annotations), and user/orchestrator docs plus UI tool presentation are updated. New contracts live in environmentUsageMcp.ts; registration tests assert tools/list includes the tool and expected input properties.

^{Reviewed by Cursor Bugbot for commit 1cf821a. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add t3_environment_usage MCP tool for environment usage summaries

• Adds a new read-only MCP tool that reads bounded daily or hourly usage summaries from UsageService and returns sanitized, paginated bucket aggregates with source status, fixed pricing provenance, and cache metadata.
• Introduces environmentUsageMcp.ts with input, result, and failure contracts; the service validates time windows (≤31 days daily, ≤24 hours hourly with local-day alignment), truncates text fields to Unicode limits, and removes source fingerprints and raw diagnostic paths.
• Registers the toolkit in McpHttpServer.ts, adds t3_environment_usage to the Claude read-only allowlist in ClaudeAdapterV2.ts, and adds its presentation label in t3McpToolPresentation.ts.
• Risk: EnvironmentUsageMcpService.make now maps all UsageReadError failures to finite public codes and drops underlying causes; any consumer relying on private error detail from the usage path will no longer receive it.

^{Macroscope summarized 1cf821a.}

[coderabbitai]

Important

Review skipped

Auto 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: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 220a6fbf-c270-48fd-8372-15259ead7971

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

Warning

Your free Security trial is over. An organization admin can activate Security or dismiss this notice.

---

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

[github-actions]

Thread transfer impact

⚠️ The latest CI run did not produce a thread transfer result for 1cf821a.

This comment will update automatically after the next completed run.

[macroscopeapp]

Effect service conventions review of the new EnvironmentUsageMcpService and its contract/toolkit wiring. Two import/module-shape findings; the service definition (inline Context.Service interface, Foo["Service"] typing, environment-acquired dependencies, no ManagedRuntime/runPromise, structured Schema.TaggedErrorClass failure with a derived message) otherwise matches the conventions.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR adds and pre-approves a new authenticated MCP capability that exposes transcript-derived usage aggregates and can trigger scans and cache refreshes. Its new service, contracts, production registration, and agent-facing behavior make it broader than an auto-approvable bounded change.

^{You can add or adjust custom eligibility rules. Learn more.}