feat(mcp): expose current environment diagnostics#8726

src/environmentMcp.ts:148

EnvironmentMcpFailure carries an unstructured message as its only payload beyond code, so the message is not derived from structural attributes and there is nowhere to preserve the underlying failure.

Consider dropping the message field, adding cause: Schema.optional(Schema.Defect()), and deriving message in an override get message() from code. Note that environment_unavailable is currently used for two genuinely different situations in EnvironmentMcpService.read (descriptor unavailable vs. credential/environment mismatch) with different caller-visible text — those should become distinct codes so each keeps its own derived message.

No longer relevant as of 0a9b7e711700353973e94c053c88f3f78cc1e628

Addressed in 0a9b7e7117. EnvironmentMcpFailure now carries only a finite structural code; its safe message is derived from that code. Credential/environment mismatch has its own environment_mismatch code, distinct from descriptor/service unavailability. I intentionally did not add Schema.Defect or a raw cause to this public MCP contract because those values can expose stacks, paths, and configuration.

failure is a helper whose only behavior is (...args) => new EnvironmentMcpFailure({ ...args }), which the conventions ask us not to add — constructing the error at each failure boundary keeps its attributes visible. Separately, unavailable discards the wrapped failure: the caught cause never reaches the returned error, so the real underlying error and stack are lost for every *_unavailable code.

Consider inlining new EnvironmentMcpFailure({ ... }) at the failure sites and threading the caught cause through (e.g. Cause.squash(cause)) as a cause attribute once the contract carries one (see the comment on packages/contracts/src/environmentMcp.ts).

^{Posted via Macroscope — Effect Service Conventions}

Addressed in 0a9b7e7117. The constructor-only failure helper was removed and each boundary now constructs EnvironmentMcpFailure with its visible structural code. The remaining unavailable helper is the common interruption-preserving redaction boundary: interruption is re-raised, while dependency failures map to a finite public reason without serializing internal stacks, paths, or configuration onto the MCP wire.

🟡 Medium mcp/EnvironmentMcpService.ts:124

A credential with a mismatched scope.environmentId receives provider_registry_unavailable or settings_unavailable when either dependency fails, instead of environment_mismatch, disclosing operational health outside its environment. Effect.all fetches provider and settings data before the binding check; validate the descriptor and environment binding before accessing those dependencies.

Fixed at c24bb8ce3264322a05c17cb3c3408c0ad5178854. The service now loads and validates the running environment descriptor before starting provider-registry or settings reads. The focused mismatch test uses read counters and proves both scoped dependencies remain unread when the credential environment differs; its partial services are typed Layer.mock fixtures. EnvironmentMcpService.test.ts passes 4/4 and the scoped server typecheck exits successfully.

unavailable still discards the caught cause: for environment_unavailable, provider_registry_unavailable, and settings_unavailable the wrapped error and its stack are lost, leaving only the code. When wrapping a real failure, the immediate underlying error should be preserved as cause alongside the structural fields.

Consider adding an optional cause: Schema.optional(Schema.Defect()) to EnvironmentMcpFailure in packages/contracts/src/environmentMcp.ts (optional because capability_denied and environment_mismatch legitimately have no underlying failure), and passing Cause.squash(cause) here: Effect.fail(new EnvironmentMcpFailure({ code, cause: Cause.squash(cause) })). Keep the message getter derived from code only, so no raw defect text reaches the wire.

^{Posted via Macroscope — Effect Service Conventions}

Declining this public-contract change. EnvironmentMcpFailure intentionally exposes only a finite code and code-derived safe message; adding Schema.Defect or a squashed cause would serialize arbitrary stack, path, provider, or configuration details across MCP. The unavailable helper preserves interruption semantics while redacting operational causes at this trust boundary. Server-side diagnostics can remain internal without widening the wire schema.

Test named-imports service layer

Low Severity

The new EnvironmentMcpService test named-imports layer and stubs ProviderRegistry with as never. Server service tags are namespace-imported so callers use EnvironmentMcpService.layer and typed Layer.mock fixtures rather than a bare layer binding or an untyped stub.

^{Triggered by learned rule: Effect services: namespace import, not named import of the Tag}

^{Reviewed by Cursor Bugbot for commit 000d34359ce5fc78b4c6d73dcbae3b9bb102d9fd. Configure here.}

Fixed in 09826107612029802ec06bacfb22d8102eac9513. The test now namespace-imports both EnvironmentMcpService and ProviderRegistry, and the two cast-away service objects are typed Layer.mock fixtures. Focused diagnostics/preferences tests pass 7/7 after upper restack; canonical t3 typecheck exits 0.