feat(den): move the external MCP session pool inside @openwork/enterprise-mcp-client, then retire the SDK client path

[benjaminshafii]

Context

PR #3208 introduced an in-process session pool for external MCP capability operations (one downstream handshake reused across search_capabilities/execute_capability instead of a fresh initialize per operation). While writing its e2e spec we found the pool was bypassed on the live path: external-mcp-client-runtime.ts had standardized list/call/inspect on @openwork/enterprise-mcp-client (#2810), while the pool lives in the den-api SDK client (external-mcp-client.ts).

The stopgap shipped in #3208 flips tool operations (listExternalMcpTools / callExternalMcpTool / inspectExternalMcpToolCall) back to the pooled SDK client, while connect/OAuth stays on the enterprise client. That splits one logical concern across two clients and partially reverses #2810's standardization.

Goal

Make @openwork/enterprise-mcp-client the single runtime again — now with pooling:

1. Move the session pool inside the enterprise client (or its Den adapter). runEnterpriseMcpOperation in ee/apps/den-api/src/capability-sources/enterprise-mcp-client-adapter.ts currently builds a client per operation and already threads lifecycleDeadline — that is where pooled acquisition slots in. Preserve the feat(den): reuse downstream MCP sessions across capability operations #3208 pool contract: per-member keying (connection row revision + membership + connected-account revision), idle/absolute TTLs, LRU, single-flight connects, evict + exactly one retry on session-shaped failures, invalidation hooks on token save/refresh/invalidate and connection mutations, and the DEN_EXTERNAL_MCP_SESSION_REUSE=0 kill switch.
2. Flip external-mcp-client-runtime.ts tool ops back to the enterprise client.
3. Retire the SDK client path (external-mcp-client.ts) once nothing routes through it.

Safety net

evals/specs/org-connector-session-reuse.test.ts proves the behavior from outside Den and is client-agnostic:

• search→execute = one downstream initialize, same session id;
• member isolation (distinct session id + token per member, negative halves asserted);
• credential rotation forces a fresh handshake;
• killed session → evict + exactly one retry;
• kill switch restores session-per-operation.

It must stay green through steps 1–3 unchanged. It has already demonstrated it discriminates: with tool ops routed to the (unpooled) enterprise client, the reuse claim fails.

Non-goals

• Any change to OAuth/DCR/PKCE handling — that is exactly what the enterprise client owns today and why we are consolidating onto it rather than away from it.

[benjaminshafii]

Sequencing: blocked by #3208 (ships the pool + stopgap routing). This issue is the immediate follow-up, not backlog — two parallel MCP client paths is how the pool got silently bypassed in the first place, so the window where both exist should be as short as possible. The spec (evals/specs/org-connector-session-reuse.test.ts) is client-agnostic and must stay green unchanged through every step here.

[benjaminshafii]

#3208 merged (c8adbe717) — this issue is now unblocked and is the active next step. Scope note from the merge: the pre-merge review was waived to ship the traffic relief, so @reachjalil's two checks fold in here — (a) per-member pool keying in external-mcp-session-pool.ts, (b) SDK-vs-enterprise tool-path parity. If (b) finds a gap, revert the routing commit from #3208 and implement the pool here directly. The spec evals/specs/org-connector-session-reuse.test.ts is on dev and must stay green unchanged through the migration.

[harrisonmichael809]

💡🙌 请问本地跑通有没有常见坑