Skip to content

Support FastMCP 4 sessions and harness sampling guards - #1304

Open
JianYan11 wants to merge 12 commits into
openenv:mainfrom
JianYan11:codex/fastmcp-4-migration
Open

JianYan11 wants to merge 12 commits into
openenv:mainfrom
JianYan11:codex/fastmcp-4-migration

Conversation

@JianYan11

@JianYan11 JianYan11 commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Upgrade the core runtime to FastMCP 4 while preserving OpenEnv's managed session semantics and migrating harness sampling to the supported guard protocol.

  • Require fastmcp>=4.0.10,<5.0.0, with the FastAPI and Pydantic floors required by SDK v2.
  • Keep managed OpenEnv clients on the legacy handshake for cross-call state; serialize tool discovery using MCP's camelCase wire aliases.
  • Mirror each harness connection's protocol era onto its stateful proxy backend, so modern sampling guards work through renamed tools without breaking legacy session isolation.
  • Add HTTP/WebSocket schema and session isolation regressions, and sampling continuation/state/progress coverage for direct and renamed harness tools.
  • Document migration behavior. Independent environment dependency manifests and lockfiles are deliberately unchanged.

Type of Change

  • Bug fix / dependency migration
  • Breaking change: the core dependency now requires FastMCP 4 rather than 3
  • Documentation

Compatibility notes

FastMCP 4 removes Context.sample() even on legacy connections. Harness tools that borrow the client's model should return InputRequiredResult with a CreateMessageRequest and consume ctx.input_responses on the continuation. The client's sampling_handler remains supported.

Sampling guards require modern connections; the legacy internal client used for managed OpenEnv tool calls does not accept modern guards. The migration is documented rather than claiming the removed API is transparently restored.

Alignment Checklist

  • Reviewed PRINCIPLES.md and INVARIANTS.md.
  • Gym API signatures and the agent/infrastructure boundary are unchanged.
  • Branch includes current upstream main.
  • CI lint, tests, environment-doc sync and package smoke checks pass.
  • No unrelated local README, client or container-provider edits included.

RFC Status

Not required: dependency migration, internal compatibility fixes and regression tests; no new public OpenEnv signatures or architectural abstractions. RFC 003/005 boundaries are preserved.

Test Plan

Completed on this exact head commit:

  • Tests CI: Linux Python 3.11/3.12 main suites, ThinkingBox suites, lint and environment-doc sync passed.
  • Package CI: build, metadata validation, wheel install and sdist install smoke tests passed.
  • Local complete core suite with FASTMCP_MCP_CAMELCASE_COMPAT=false: 834 passed, 1 skipped.
  • New sampling test first failed on the renamed bridge because its backend negotiated the legacy era; it passes after the protocol mirroring fix.
  • Changed-file formatting/lint and git diff --check pass.

The standalone local lint hook reports the same existing usort/Ruff formatting differences as the clean upstream baseline (including environment Markdown). The repository's exact CI lint pipeline passes. No unrelated mass formatting is included. The local test hook requires GNU timeout, absent on this macOS host; the full Linux CI selection was run instead.

Review Notes

No new debugger statements, public Gym signature changes, reward relocation or agent access to simulation controls. External-service/network/Docker-marked tests remain excluded by the existing CI configuration.


Note

High Risk
Breaking dependency upgrade touches core MCP session handling, HTTP tool discovery, and harness protocol negotiation; regressions could affect production MCP clients and cross-call tool state.

Overview
Upgrades the core runtime to FastMCP 4 (fastmcp>=4.0.10) with bumped FastAPI and Pydantic floors, and adapts OpenEnv so managed MCP sessions and harness tooling still behave as before.

Managed MCP sessions now connect internal clients with Client(..., mode="legacy") so ctx.get_state() / ctx.set_state() persist across tool calls within an OpenEnv HTTP or WebSocket session. Tool discovery maps FastMCP’s input_schema to the wire inputSchema alias (e.g. model_dump(by_alias=True) on HTTP).

Harness bridge mirrors each front connection’s protocol era onto the stateful proxy backend so modern sampling guards (InputRequiredResult / ctx.input_responses) work through renamed tools, while legacy connections keep per-session state isolation.

Docs describe the FastMCP 4 session model and the migration away from Context.sample(). CI runs τ²-bench tests from a new tests/tau2_runtime project with lock checks; regression tests cover schema aliases, session isolation, and harness sampling/state/progress.

Reviewed by Cursor Bugbot for commit b3ae6ac. Bugbot is set up for automated code reviews on this repo. Configure here.

@burtenshaw

Copy link
Copy Markdown
Collaborator

cursor review

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

Reviewed by Cursor Bugbot for commit 2f3fa79. Configure here.

@bot-ci-comment

bot-ci-comment Bot commented Oct 3, 2026

Copy link
Copy Markdown

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

@burtenshaw

burtenshaw commented Oct 26, 2026 •

Copy link
Copy Markdown
Collaborator

Reviewed and refreshed this migration at source-branch head 042beb4f23f3c0247057036c512b1f2d81c4b15e (normal push, includes main 43df9edb). The sole conflict was the deleted lifecycle guide: preserved main's docs consolidation and moved the migration notes into Simulation vs Production. Added direct-tool coverage to the existing legacy harness isolation/reconnect regression. No production-code changes beyond the original migration.

Independent validation (Python 3.12, FASTMCP_MCP_CAMELCASE_COMPAT=false):

  • FastMCP 4.0.10 minimum: focused MCP/production/harness suite 190 passed, 1 skipped; complete tests/core 883 passed, 9 skipped.
  • FastMCP 4.1.4: original focused suite 189 passed, 1 skipped (before the extra direct legacy parameter).
  • Real HTTP/WebSocket managed state persistence and isolation, closed-session replacement, direct/renamed harness legacy isolation, and modern sampling continuation/request-state/progress forwarding passed.
  • Changed Python files pass Ruff, format and usort; runtime lock check and diff check pass. Broad lint hook still reports unrelated baseline formatting; no new debugger code.

Not recommending merge yet: this is a breaking protocol migration, not a safe dependency-ceiling bump. A real managed-client probe confirms InputRequiredResult becomes EXECUTION_ERROR: the internal client negotiates 2025-11-25, while guards require 2026-07-28. Context.sample() is removed even for legacy clients. This limitation is documented, but maintainers should explicitly accept dropping this sampling path (including old harness clients), decide the release/deprecation treatment under INVARIANTS.md, or require a separately designed compatibility approach. Modern harness guard support does not restore managed-client sampling. Suggested alignment reviewers: @Darktex and @sergiopaniego (boundary/deprecation guidance).

Final read-back confirms PR and fork head both equal 042beb4f23f3c0247057036c512b1f2d81c4b15e: MERGEABLE/BLOCKED, with all five new-head workflows queued. Main remains 43df9edb. No workflow currently requires approval. Parent owns exact-head CI and the migration decision. No merge/close and no polling/watch performed; #1331 unchanged.

Resolve validation-runtime FastMCP conflict with 4.1.2, the 4.x release containing the transformed-component authorization fixes backported in main 3.4.10. Retain unrelated dependency versions and existing legacy/protocol behavior; release acceptance remains a maintainer gate.
tests/validation_runtime/uv.lock conflicted with main's pillow 13 and
gradio 6.32 relock (openenv#1620). Take main's lock and relock with fastmcp
pinned to 4.1.2, which reproduces this branch's six package changes.
Relock tests/tau2_runtime too: main's root pyproject moved on, so its
openenv metadata was stale and uv lock --check failed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@burtenshaw

Copy link
Copy Markdown
Collaborator

Merged main in b3ae6ac. #1620 relocked tests/validation_runtime/uv.lock for pillow 13 and gradio 6.32, which conflicted with this branch. I took main's lock and relocked it with fastmcp pinned to 4.1.2, so it carries the same six package changes as before.

tests/tau2_runtime/uv.lock also needed a relock: the root pyproject.toml changed on main (version and extras), so its openenv metadata was stale. No package versions changed. uv lock --check passes for both.

@burtenshaw

Copy link
Copy Markdown
Collaborator

After the main merge, CI fails in two places. Both come from envs that landed after this branch was last updated, not from the lock changes.

  1. test (3.11) and test (3.12): envs/posttrain_env (Add experimental posttrain_env prototype (RFC 014) #1500). It imports ToolResult from fastmcp.tools.tool, which FastMCP 4 removed, so test collection fails. from fastmcp.tools import ToolResult works on both 3 and 4, but it is not enough. With that change, 92 of the 103 posttrain tests fail under FastMCP 4.1.8 with 'dict' object has no attribute 'model_dump' from the tool calls. On main with FastMCP 3.4.11 all 103 pass. So posttrain_env needs the same migration as the other MCP environments.
  2. test-ortools-env (Add OR-Tools environment #1501). The job installs envs/ortools_env from its own lock, which brings FastMCP 3 through the published openenv. It then runs the tests with PYTHONPATH=src:envs, so this branch's core calls Client(..., mode="legacy") against FastMCP 3 and fails with unexpected keyword argument 'mode'. tests/tau2_runtime already solves this for the tau2 job, and the OR-Tools job needs the same treatment.

This branch has not been deployed

No deployments
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.

2 participants