feat(eve): stateful MCP client sessions

[ckblockit]

Summary

Adds a session: "stateful" option to defineMcpClientConnection. When set, an MCP connection persists its server-assigned Mcp-Session-Id across eve step boundaries, so a stateful MCP server (one that returns Mcp-Session-Id on initialize, per the MCP spec) sees one continuous session for the life of the eve session instead of a net-new session every step.

defineMcpClientConnection({
  url: "https://mcp.example.com",
  description: "...",
  session: "stateful", // default: "stateless" (unchanged behavior)
})

The problem

eve rebuilds the connection registry on every step — it's a derived context key holding live client instances that can't survive a step boundary. So each step created a fresh @ai-sdk/mcp client, opened a new transport, and sent a new initialize, getting a new Mcp-Session-Id every step. The previously negotiated session was never captured or persisted, so a stateful MCP server treated every step as a brand-new session.

How it works

The work splits into cheap replay and a small capture:

• Replay (steps 2…N): inject the persisted Mcp-Session-Id as a request header.
• Capture (first initialize): read the Mcp-Session-Id off the server's response.

Both happen through a custom fetch passed to @ai-sdk/mcp's HTTP transport, driven by a per-step mutable "slot". Persistence mirrors the existing sandboxProvider:

1. session flows from the public definition → ResolvedConnectionDefinition.
2. connectionProvider.create seeds a slot from session.state, keyed by mcpSessionStateKey(connectionName, principalId).
3. The registry hands each stateful McpConnectionClient its slot; the client's fetch wrapper injects + captures the Mcp-Session-Id.
4. On a server 404 (expired/unknown session), the client clears the slot, closes, and re-initializes once.
5. connectionProvider.commit drains changed ids back into session.state, which survives the step boundary.

Scoping: per connection + authenticated principal, with an "anonymous" fallback for unauthenticated callers. session.state is itself per-eve-session, so there's no cross-session or cross-principal leakage.

Stateless connections are unchanged — no slot, no fetch wrapper, no retry.

Deliberately deferred: HTTP DELETE termination

The MCP spec says a client SHOULD send DELETE to terminate a session when done. eve has no clean per-eve-session "end" hook (commit/dispose run every step; HarnessSession has no terminal flag), and firing DELETE at any existing hook would kill the session we're deliberately persisting. Since DELETE is SHOULD (not MUST) and correctness is preserved by server-side TTL + the mandatory 404 re-init path, it's left as a follow-up rather than adding session-lifecycle plumbing here.

Testing

• Unit: key derivation (principal vs. anonymous), stateful-vs-stateless header injection, 404 → re-init, the fetch wrapper's inject/capture/no-clobber, and the connectionProvider create→commit round-trip (persist + re-seed across a simulated step boundary).
• A regression test confirms a 404 while replaying a persisted session re-initializes over HTTP rather than falling back to SSE (it fails without the guard).
• 161 unit tests green across the touched areas; typecheck, lint, fmt, guard:invariants, and docs:check all pass.

Changeset

patch — new feature, pre-1.0.

🤖 Generated with Claude Code

[vercel]

@ckblockit is attempting to deploy a commit to the Vercel Team on Vercel.

A member of the Team first needs to authorize it.

[ckblockit]

@allenzhou101 could you review this when you have a chance? Thanks! (Requesting via comment — I'm contributing from a fork, so I can't assign you as a formal reviewer.)