fix: rename platform to os and add new availability axes for provider, target, and surface#433
Open
frontegg-david wants to merge 1 commit into
Open
fix: rename platform to os and add new availability axes for provider, target, and surface#433frontegg-david wants to merge 1 commit into
frontegg-david wants to merge 1 commit into
Conversation
…, target, and surface
Contributor
📝 WalkthroughWalkthroughThis PR implements expanded environment availability axes for granular entry filtering. It adds runtime detection for deployment providers (Vercel, Lambda, Cloudflare, etc.) and build targets, introduces per-request surface filtering, and extends error handling to report which constraint axes failed—enabling better client-side diagnostics when tools become unavailable. ChangesEnvironment Availability Axes Expansion
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related issues
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
docs/frontmcp/features/environment-awareness.mdx (2)
330-342:⚠️ Potential issue | 🟠 Major | ⚡ Quick winInconsistent error format: Missing
missingAxesfield.This section documents an
EntryUnavailableErrorresponse without themissingAxesfield, but Lines 160-180 (Structured errors section) document the same error scenario with amissingAxesarray. Both describe "tool exists but is unavailable in the current environment."Per the guideline and issue
#417, the error should includemissingAxesin itsdatapayload. Either update this example to match the structured error format, or clarify that this section shows a legacy format and reference the Structured errors section for the current implementation.🔧 Suggested fix: Update to structured error format
{ "code": -32003, - "message": "Tool \"apple_notes_search\" is not available in the current environment (requires: {\"platform\":[\"darwin\"]}) (current: {\"platform\":\"linux\",\"runtime\":\"node\",\"deployment\":\"standalone\",\"env\":\"production\"})" + "message": "Tool \"apple_notes_search\" is not available in the current environment ...", + "data": { + "entryType": "Tool", + "entry": "apple_notes_search", + "missingAxes": ["os"], + "constraint": { "os": ["darwin"] }, + "context": { "os": "linux", "runtime": "node", "deployment": "standalone", "env": "production", ... } + } }Note: Also changed
platformtoosto use the non-deprecated field name.🤖 Prompt for 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. In `@docs/frontmcp/features/environment-awareness.mdx` around lines 330 - 342, Update the EntryUnavailableError example so it uses the structured error format: include a data object with a missingAxes array (e.g., listing the unavailable axis "os": ["darwin"]) and replace deprecated "platform" with "os"; ensure the JSON message, code (-32003) and error name EntryUnavailableError remain, and either reference the Structured errors section or mirror its exact schema so this example matches the implemented structured error payload.
267-273:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winClarify the relationship between the
osproperty andisPlatform()method in the Runtime Context API section.The
RuntimeContextinterface has been renamed to useosas the primary property (withplatformas a deprecated alias per issue#417), but the table only documentsisPlatform()method. Either:
- If
isOs()is planned: Add it to the table and note thatisPlatform()is deprecated.- If
isPlatform()remains the only method: Update the table to explain thatisPlatform()checks against the deprecated.platformproperty, and clarify that users should access.osdirectly or the method should be updated to use.os.Additionally, consider adding a row for direct property access (e.g.,
this.runtimeContext.os) to show the modern way to check the OS axis.🤖 Prompt for 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. In `@docs/frontmcp/features/environment-awareness.mdx` around lines 267 - 273, Update the Runtime Context API docs to clarify the os/platform relationship: state that RuntimeContext now exposes the OS via the os property (RuntimeContext.os) and that platform is a deprecated alias; then either add a new table row for direct property access (this.runtimeContext.os → string | Description: modern OS axis access) and, if an isOs() helper exists or will be added, add a row for isOs() and mark isPlatform() as deprecated, or if isPlatform() remains the only helper, update its table entry to note that isPlatform() checks the deprecated .platform alias and recommend using this.runtimeContext.os (or an isOs() helper) going forward. Ensure you reference RuntimeContext, os, platform, isPlatform(), isOs(), and this.runtimeContext.os in the text so readers can locate the code/API.
🧹 Nitpick comments (4)
docs/frontmcp/features/environment-awareness.mdx (3)
293-302: ⚡ Quick winUse
osinstead of deprecatedplatformin multi-platform example.The multi-platform pattern example uses the deprecated
platformfield. Update toosto demonstrate the preferred axis name.📝 Suggested fix
`@Tool`({ name: 'notes_search', description: 'Search notes on this system', inputSchema: { query: z.string() }, - availableWhen: { platform: ['darwin'] }, + availableWhen: { os: ['darwin'] }, })🤖 Prompt for 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. In `@docs/frontmcp/features/environment-awareness.mdx` around lines 293 - 302, Update the `@Tool` decorator's availability axis: replace the deprecated availableWhen: { platform: ['darwin'] } with availableWhen: { os: ['darwin'] } in the AppleNotesSearchTool declaration (the `@Tool` with name 'notes_search' and class AppleNotesSearchTool) so the example uses the current os field for multi-platform scoping.
26-26: ⚡ Quick winUse the preferred
osfield instead of deprecatedplatformalias.The example introduces
availableWhenusing the deprecatedplatformfield. Since Line 57 explicitly documentsplatformas a deprecated alias foros, examples should demonstrate the preferred, non-deprecated name to guide users toward current best practices.📝 Suggested fix
- availableWhen: { platform: ['darwin'] }, + availableWhen: { os: ['darwin'] },🤖 Prompt for 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. In `@docs/frontmcp/features/environment-awareness.mdx` at line 26, Replace the deprecated "platform" alias with the preferred "os" field in the example: update the availableWhen object (symbol: availableWhen) so it uses os instead of platform (reference: the existing platform: ['darwin'] entry) to demonstrate the non-deprecated usage.
188-240: ⚡ Quick winUpdate all entry type examples to use
osinstead of deprecatedplatform.The examples in the Tabs demonstrate
availableWhenusage across all five entry types (Tool, Resource, Prompt, Skill, Agent), but all use the deprecatedplatformfield. Update them to useosto demonstrate the preferred, non-deprecated axis name.📝 Suggested changes
Replace
platform: ['darwin']withos: ['darwin']in:
- Line 194 (Tool example)
- Line 204 (Resource example)
- Line 214 (Prompt example)
- Line 225 (Skill example)
- availableWhen: { platform: ['darwin'] }, + availableWhen: { os: ['darwin'] },Also update Line 204 (Resource example):
- availableWhen: { platform: ['darwin', 'linux'] }, + availableWhen: { os: ['darwin', 'linux'] },🤖 Prompt for 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. In `@docs/frontmcp/features/environment-awareness.mdx` around lines 188 - 240, Update the examples to use the non-deprecated axis name "os" instead of "platform": replace availableWhen: { platform: [...] } with availableWhen: { os: [...] } in the Tool example (AppleNotesSearchTool), Resource example (SystemInfoResource), Prompt example (XcodeReviewPrompt), Skill example (IosDeploySkill), and Agent example (LocalBuildAgent); ensure you also change the Resource entry that currently lists both darwin and linux to use os: ['darwin', 'linux'] so all snippets consistently use "os".libs/skills/catalog/frontmcp-development/references/create-tool.md (1)
558-570: ⚡ Quick winUse
osinstead of deprecatedplatformin macOS-only tool example.This example demonstrates platform-specific tooling but uses the deprecated
platformfield. Per Lines 588,osis the preferred name withplatformkept as a deprecated alias. Update the example to useos.📝 Suggested fix
// macOS-only tool `@Tool`({ name: 'apple_notes_search', description: 'Search Apple Notes', inputSchema: { query: z.string() }, - availableWhen: { platform: ['darwin'] }, + availableWhen: { os: ['darwin'] }, })🤖 Prompt for 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. In `@libs/skills/catalog/frontmcp-development/references/create-tool.md` around lines 558 - 570, Update the macOS-only tool example to use the newer availableWhen.os key instead of the deprecated availableWhen.platform: in the `@Tool` decorator for AppleNotesSearchTool replace availableWhen: { platform: ['darwin'] } with availableWhen: { os: ['darwin'] } so the Tool metadata uses os (platform is only a deprecated alias).
🤖 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.
Outside diff comments:
In `@docs/frontmcp/features/environment-awareness.mdx`:
- Around line 330-342: Update the EntryUnavailableError example so it uses the
structured error format: include a data object with a missingAxes array (e.g.,
listing the unavailable axis "os": ["darwin"]) and replace deprecated "platform"
with "os"; ensure the JSON message, code (-32003) and error name
EntryUnavailableError remain, and either reference the Structured errors section
or mirror its exact schema so this example matches the implemented structured
error payload.
- Around line 267-273: Update the Runtime Context API docs to clarify the
os/platform relationship: state that RuntimeContext now exposes the OS via the
os property (RuntimeContext.os) and that platform is a deprecated alias; then
either add a new table row for direct property access (this.runtimeContext.os →
string | Description: modern OS axis access) and, if an isOs() helper exists or
will be added, add a row for isOs() and mark isPlatform() as deprecated, or if
isPlatform() remains the only helper, update its table entry to note that
isPlatform() checks the deprecated .platform alias and recommend using
this.runtimeContext.os (or an isOs() helper) going forward. Ensure you reference
RuntimeContext, os, platform, isPlatform(), isOs(), and this.runtimeContext.os
in the text so readers can locate the code/API.
---
Nitpick comments:
In `@docs/frontmcp/features/environment-awareness.mdx`:
- Around line 293-302: Update the `@Tool` decorator's availability axis: replace
the deprecated availableWhen: { platform: ['darwin'] } with availableWhen: { os:
['darwin'] } in the AppleNotesSearchTool declaration (the `@Tool` with name
'notes_search' and class AppleNotesSearchTool) so the example uses the current
os field for multi-platform scoping.
- Line 26: Replace the deprecated "platform" alias with the preferred "os" field
in the example: update the availableWhen object (symbol: availableWhen) so it
uses os instead of platform (reference: the existing platform: ['darwin'] entry)
to demonstrate the non-deprecated usage.
- Around line 188-240: Update the examples to use the non-deprecated axis name
"os" instead of "platform": replace availableWhen: { platform: [...] } with
availableWhen: { os: [...] } in the Tool example (AppleNotesSearchTool),
Resource example (SystemInfoResource), Prompt example (XcodeReviewPrompt), Skill
example (IosDeploySkill), and Agent example (LocalBuildAgent); ensure you also
change the Resource entry that currently lists both darwin and linux to use os:
['darwin', 'linux'] so all snippets consistently use "os".
In `@libs/skills/catalog/frontmcp-development/references/create-tool.md`:
- Around line 558-570: Update the macOS-only tool example to use the newer
availableWhen.os key instead of the deprecated availableWhen.platform: in the
`@Tool` decorator for AppleNotesSearchTool replace availableWhen: { platform:
['darwin'] } with availableWhen: { os: ['darwin'] } so the Tool metadata uses os
(platform is only a deprecated alias).
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: cfcc2e1b-18bf-4592-9363-d066e20083a3
📒 Files selected for processing (13)
docs/frontmcp/features/environment-awareness.mdxlibs/sdk/src/errors/mcp.error.tslibs/sdk/src/tool/flows/call-tool.flow.tslibs/sdk/src/transport/mcp-handlers/call-tool-request.handler.tslibs/skills/catalog/frontmcp-development/references/create-tool.mdlibs/utils/src/env/__tests__/availability-axes.spec.tslibs/utils/src/env/__tests__/build-target.spec.tslibs/utils/src/env/__tests__/provider.spec.tslibs/utils/src/env/browser-runtime-context.tslibs/utils/src/env/build-target.tslibs/utils/src/env/index.tslibs/utils/src/env/provider.tslibs/utils/src/env/runtime-context.ts
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary by CodeRabbit
New Features
os,provider,target,surface) for more granular feature gating across different platforms and deployment scenarios.Documentation