Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
feat(mcp-host): add idempotent per-turn catalog bootstrap (spec 13 phase 4)
Diego Zacarias2ad7cea1636f
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.jsonindex c768862a2..f6200ec47 100644--- a/mcp-host/package-lock.json+++ b/mcp-host/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-mcp-host",- "version": "0.1.375",+ "version": "0.1.376","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-mcp-host",- "version": "0.1.375",+ "version": "0.1.376","license": "SEE LICENSE IN LICENSE","dependencies": {"@anthropic-ai/sdk": "^0.32.0",diff --git a/mcp-host/package.json b/mcp-host/package.jsonindex 9021b03f0..4d3f5cb58 100644--- a/mcp-host/package.json+++ b/mcp-host/package.json@@ -1,6 +1,6 @@{"name": "clerum-mcp-host",- "version": "0.1.375",+ "version": "0.1.376","description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude","main": "dist/main.js","engines": {diff --git a/mcp-host/src/mcp/__tests__/grantRevocationSweep.test.ts b/mcp-host/src/mcp/__tests__/grantRevocationSweep.test.tsindex 11e9c006f..cdec76d64 100644--- a/mcp-host/src/mcp/__tests__/grantRevocationSweep.test.ts+++ b/mcp-host/src/mcp/__tests__/grantRevocationSweep.test.ts@@ -25,9 +25,24 @@ import {checkGrantExistence,selectRevokedPartitionKeys,} from '../grantExistenceClient'+import type { GrantExistenceChecker, McpCatalogBootstrapConfig } from '../grantProbe'import { type LiveOAuthPartition, McpManager, serializeClientKey, userPrincipal } from '../manager'import { type RemoteUpstreamState, brokerWiring, sweepOnce } from './helpers/brokerWiring'+/** Bootstrap config for the inv-18 sweep case (values are irrelevant to the sweep). */+function sweepBootstrapConfig(): McpCatalogBootstrapConfig {+ return {+ enabled: true,+ waitBudgetMs: 4000,+ probeTimeoutMs: 2000,+ connectTimeoutMs: 8000,+ negativeTtlMs: 15000,+ failureTtlMs: 60000,+ probesPerMin: 20,+ backoffMs: 30000,+ }+}+// ─── transport-aware SDK mock (Bearer presence drives the 401) ────────────────// The lenient upstream (accepts initialize token-less, 401s at tools/call) and// the broker+exists wiring both come from the shared helper (T1: one source of@@ -282,6 +297,40 @@ describe('listLiveOAuthPartitions', () => {},])})++ // ── invariant 18: a bootstrapped partition is a full-fledged sweep subject ──+ it('a bootstrapped partition appears in the sweep and is evicted on exists:false', async () => {+ const grantStore = new Set(['gh:alice'])+ const { deps, factory } = brokerWiring(grantStore)+ const grantExistence: GrantExistenceChecker = (queries, { timeoutMs }) =>+ checkGrantExistence({ ...deps, timeoutMs }, queries)+ const manager = new McpManager(undefined, undefined, factory, {+ grantExistence,+ catalogBootstrap: sweepBootstrapConfig(),+ })+ // The bootstrap only considers REMOTE oauth servers (M1/M2).+ await manager.addServer({ ...oauthUserServer('gh'), remote: true })++ // No prior callTool: the partition is opened by the bootstrap alone.+ const summary = await manager.bootstrapUserCatalog('alice')+ expect(summary.admitted).toBe(1)++ // It is exposed to the sweep exactly like a lazily-admitted partition.+ const live = manager.listLiveOAuthPartitions()+ expect(live).toEqual([+ {+ flavor: 'oauth-user',+ serverName: 'gh',+ userId: 'alice',+ key: serializeClientKey('gh', userPrincipal('alice')),+ },+ ])++ // Revoke the grant → the sweep evicts the bootstrapped partition.+ grantStore.delete('gh:alice')+ expect(await sweepOnce(manager, deps)).toBe(1)+ expect(manager.listLiveOAuthPartitions()).toEqual([])+ })})// ─── client unit tests ───────────────────────────────────────────────────────diff --git a/mcp-host/src/mcp/__tests__/helpers/brokerWiring.ts b/mcp-host/src/mcp/__tests__/helpers/brokerWiring.tsindex c03c294ef..600761dea 100644--- a/mcp-host/src/mcp/__tests__/helpers/brokerWiring.ts+++ b/mcp-host/src/mcp/__tests__/helpers/brokerWiring.ts@@ -37,6 +37,8 @@ export interface BrokerWiring {factory: McpTokenProviderFactory/** Every `/grants/exists` batch POSTed, in order (assert probe count/coordinates). */existsCalls: Array<Array<{ mcpServerName: string; userId?: string }>>+ /** Every `/user-token` mint POSTed, in order (assert no token spent without a grant). */+ userTokenCalls: Array<{ mcpServerName: string; userId?: string }>/** Force the next `/grants/exists` responses to a non-200 (throws at the client). */failExistsWith: (status: number) => void}@@ -49,10 +51,12 @@ export interface BrokerWiring {*/export function brokerWiring(grantStore: Set<string>): BrokerWiring {const existsCalls: Array<Array<{ mcpServerName: string; userId?: string }>> = []+ const userTokenCalls: Array<{ mcpServerName: string; userId?: string }> = []let existsStatus = 200const fetchImpl = vi.fn(async (url: string, init: RequestInit) => {const body = JSON.parse(init.body as string)if (url.endsWith('/api/v1/mcp-oauth/user-token')) {+ userTokenCalls.push({ mcpServerName: body.mcpServerName, userId: body.userId })const has = grantStore.has(`${body.mcpServerName}:${body.userId ?? ''}`)return (has? {@@ -97,7 +101,13 @@ export function brokerWiring(grantStore: Set<string>): BrokerWiring {}return { resolve: async () => undefined, refresh: async () => undefined }}- return { deps, factory, existsCalls, failExistsWith: (s: number) => (existsStatus = s) }+ return {+ deps,+ factory,+ existsCalls,+ userTokenCalls,+ failExistsWith: (s: number) => (existsStatus = s),+ }}/** The revocation sweep exactly as main.ts wires it (no duplicated decision logic). */@@ -129,6 +139,9 @@ export interface RemoteUpstreamState {callToolImpl: ((auth: string) => Promise<unknown>) | null/** Count of 401s the lenient upstream raised at `tools/call` (missing Bearer). */toolCall401Count: number+ /** Optional gate the (authenticated) `connect` awaits — lets a test control or+ * hang a bootstrap admission to exercise the wait/connect budgets. */+ connectGate?: (() => Promise<void>) | null}export interface RemoteUpstreamMocks {@@ -144,7 +157,13 @@ const TOOLS_RESULT = {/** A fresh mutable upstream state. Share ONE across a file's SDK mock factories. */export function createUpstreamState(): RemoteUpstreamState {- return { transports: [], probeAuth: [], callToolImpl: null, toolCall401Count: 0 }+ return {+ transports: [],+ probeAuth: [],+ callToolImpl: null,+ toolCall401Count: 0,+ connectGate: null,+ }}/** A 401 raised at `initialize` by a spec-compliant remote (strict variant). */@@ -179,6 +198,9 @@ export function remoteUpstream(if (strict && t.url.startsWith('https:') && !t.requestHeaders['Authorization']) {throw new RemoteAuthRequired()}+ // An optional gate lets a test delay or hang an authenticated connect (the+ // bootstrap wait/connect budgets). It runs only past the strict 401 check.+ if (state.connectGate) await state.connectGate()this.transport = t})close = vi.fn().mockResolvedValue(undefined)diff --git a/mcp-host/src/mcp/__tests__/managerCatalogBootstrap.test.ts b/mcp-host/src/mcp/__tests__/managerCatalogBootstrap.test.tsnew file mode 100644index 000000000..3c225a19e--- /dev/null+++ b/mcp-host/src/mcp/__tests__/managerCatalogBootstrap.test.ts@@ -0,0 +1,357 @@+/**+ * Eager per-user catalog bootstrap (spec §6.1, invariants 1/2/5/6/7/10/11/13/17).+ * `bootstrapUserCatalog(userId)` opens the remote oauth-user partitions the user+ * already has a grant for so the FIRST turn's catalog carries their tools —+ * without a prior failed `callTool` — while staying idempotent, bounded, and+ * best-effort.+ *+ * Fixtures come from the shared helper (T1): `brokerWiring` serves BOTH the probe+ * (`/grants/exists`) and the token mint (`/user-token`) from ONE grant store, so+ * "grant exists" means the identical thing to the bootstrap's decision and to the+ * connection's Authorization; `remoteUpstream({strict:true})` is the real+ * McpClient over a spec-compliant SDK mock (401 at token-less `initialize`).+ * Assertions are observable (T4): the catalog (`getAllTools`), the transports the+ * SDK constructed, the `/grants/exists` and `/user-token` POST counts, and the+ * returned summary.+ */+import { beforeEach, describe, expect, it, vi } from 'vitest'+import { logger } from '../../logger'+import type { McpServerInfo } from '../../types'+import { checkGrantExistence } from '../grantExistenceClient'+import type { GrantExistenceChecker, McpCatalogBootstrapConfig } from '../grantProbe'+import { McpManager } from '../manager'+import { type RemoteUpstreamState, brokerWiring } from './helpers/brokerWiring'++// Strict (Slack/Notion-like) upstream + shared state. Plain literal in a+// synchronous vi.hoisted (imports aren't resolved that early); each vi.mock+// factory dynamically imports the builder.+const sdk = vi.hoisted<RemoteUpstreamState>(() => ({+ transports: [],+ probeAuth: [],+ callToolImpl: null,+ toolCall401Count: 0,+ connectGate: null,+}))+vi.mock('@modelcontextprotocol/sdk/client/index.js', async () => {+ const { remoteUpstream } = await import('./helpers/brokerWiring')+ return remoteUpstream({ strict: true }, sdk).clientModule+})+vi.mock('@modelcontextprotocol/sdk/client/streamableHttp.js', async () => {+ const { remoteUpstream } = await import('./helpers/brokerWiring')+ return remoteUpstream({ strict: true }, sdk).transportModule+})+vi.mock('@modelcontextprotocol/sdk/client/sse.js', async () => {+ const { remoteUpstream } = await import('./helpers/brokerWiring')+ return remoteUpstream({ strict: true }, sdk).sseModule+})++// The real SSRF guard is exercised in clientRemoteTarget.test.ts; here it must+// never touch DNS (the SDK is mocked, so its returned fetch is never invoked).+vi.mock('../../core/net/ssrf', () => ({+ SsrfBlockedError: class SsrfBlockedError extends Error {},+ resolvePinnedPublicIp: vi.fn(async () => '203.0.113.10'),+ pinnedFetch: vi.fn(() => vi.fn(async () => new Response('{}'))),+}))++function remoteOauthUserServer(name = 'gh'): McpServerInfo {+ return {+ name,+ transport: { type: 'streamableHttp', url: `https://${name}.example.com/mcp` },+ authKind: 'oauth-user',+ remote: true,+ enabled: true,+ status: { deployed: true, ready: true },+ }+}++function bootstrapConfig(over: Partial<McpCatalogBootstrapConfig> = {}): McpCatalogBootstrapConfig {+ return {+ enabled: true,+ waitBudgetMs: 4000,+ probeTimeoutMs: 2000,+ connectTimeoutMs: 8000,+ negativeTtlMs: 15000,+ failureTtlMs: 60000,+ probesPerMin: 20,+ backoffMs: 30000,+ ...over,+ }+}++interface Gated {+ manager: McpManager+ existsCalls: ReturnType<typeof brokerWiring>['existsCalls']+ userTokenCalls: ReturnType<typeof brokerWiring>['userTokenCalls']+ failExistsWith: ReturnType<typeof brokerWiring>['failExistsWith']+ /** vi.fn wrapper around the checker so a test can assert it was NOT invoked. */+ checkerSpy: ReturnType<typeof vi.fn>+}++function gatedManager(+ grantStore: Set<string>,+ cfgOver: Partial<McpCatalogBootstrapConfig> = {},+ now?: () => number,+ userPartitionMax?: number+): Gated {+ const { deps, factory, existsCalls, userTokenCalls, failExistsWith } = brokerWiring(grantStore)+ const checkerSpy = vi.fn<GrantExistenceChecker>((queries, { timeoutMs }) =>+ checkGrantExistence({ ...deps, timeoutMs }, queries)+ )+ const manager = new McpManager(undefined, undefined, factory, {+ grantExistence: checkerSpy,+ catalogBootstrap: bootstrapConfig(cfgOver),+ userPartitionMax,+ now,+ })+ return { manager, existsCalls, userTokenCalls, failExistsWith, checkerSpy }+}++beforeEach(() => {+ sdk.transports = []+ sdk.callToolImpl = null+ sdk.toolCall401Count = 0+ sdk.connectGate = null+})++describe('bootstrapUserCatalog (spec §6.1)', () => {+ // ── invariant 1 ──+ it('exposes an oauth-user tool on the first turn (no prior callTool)', async () => {+ const grantStore = new Set(['gh:alice'])+ const { manager, existsCalls } = gatedManager(grantStore)+ await manager.addServer(remoteOauthUserServer())++ // Before the bootstrap the per-user catalog is empty (no partition yet).+ expect(manager.getAllTools()).toEqual([])++ const summary = await manager.bootstrapUserCatalog('alice')++ expect(summary.candidates).toBe(1)+ expect(summary.admitted).toBe(1)+ // Observable (T4): the tool is in the catalog and the definitions list.+ expect(manager.getAllTools().map(t => t.name)).toEqual(['gh__do'])+ // One probe; the admitted partition authenticated with alice's Bearer.+ expect(existsCalls).toEqual([[{ mcpServerName: 'gh', userId: 'alice' }]])+ expect(sdk.transports).toHaveLength(1)+ expect(sdk.transports[0]!.requestHeaders['Authorization']).toBe('Bearer tok-alice')+ })++ // ── invariant 2 ──+ it('no grant ⇒ no partition, no /user-token, no initialize', async () => {+ const grantStore = new Set<string>() // no grant+ const { manager, existsCalls, userTokenCalls } = gatedManager(grantStore)+ await manager.addServer(remoteOauthUserServer())++ const summary = await manager.bootstrapUserCatalog('alice')++ expect(summary.candidates).toBe(1)+ expect(summary.admitted).toBe(0)+ expect(summary.skipped.absent).toBe(1)+ // No connection was ever attempted → no initialize, no token minted.+ expect(sdk.transports).toEqual([])+ expect(userTokenCalls).toEqual([])+ expect(manager.getAllTools()).toEqual([])+ // The probe DID run (single source of truth for the absence).+ expect(existsCalls).toEqual([[{ mcpServerName: 'gh', userId: 'alice' }]])+ })++ // ── invariant 5 ──+ it('N concurrent + N sequential ⇒ 1 POST, 1 connect (dedup)', async () => {+ const grantStore = new Set(['gh:alice'])+ const { manager, existsCalls } = gatedManager(grantStore)+ await manager.addServer(remoteOauthUserServer())++ // Concurrent: three turns of the same user coalesce onto one plan/probe/admit.+ const [a, b, c] = await Promise.all([+ manager.bootstrapUserCatalog('alice'),+ manager.bootstrapUserCatalog('alice'),+ manager.bootstrapUserCatalog('alice'),+ ])+ expect(existsCalls).toHaveLength(1)+ expect(sdk.transports).toHaveLength(1)+ expect([a.candidates, b.candidates, c.candidates]).toEqual([1, 1, 1])++ // Sequential: the partition is now live → zero candidates, zero round-trips.+ const again = await manager.bootstrapUserCatalog('alice')+ expect(again.candidates).toBe(0)+ expect(existsCalls).toHaveLength(1)+ expect(sdk.transports).toHaveLength(1)+ expect(manager.getAllTools().map(t => t.name)).toEqual(['gh__do'])+ })++ // ── invariant 6 ──+ it('steady-state (all partitions live) never calls the checker', async () => {+ const grantStore = new Set(['gh:alice'])+ const { manager, checkerSpy } = gatedManager(grantStore)+ await manager.addServer(remoteOauthUserServer())+ await manager.bootstrapUserCatalog('alice') // partition now live+ checkerSpy.mockClear()++ const summary = await manager.bootstrapUserCatalog('alice')+ expect(summary.candidates).toBe(0)+ expect(checkerSpy).not.toHaveBeenCalled()+ })++ // ── invariant 7 ──+ it('checker error ⇒ registry still built, probe_unknown, and backoff skips the next turn', async () => {+ let clock = 1_000+ const grantStore = new Set(['gh:alice'])+ const { manager, existsCalls, failExistsWith } = gatedManager(grantStore, {}, () => clock)+ await manager.addServer(remoteOauthUserServer())+ failExistsWith(500) // /grants/exists 5xx → execute throws++ const summary = await manager.bootstrapUserCatalog('alice')+ // The turn is not broken: a summary is returned, nothing admitted.+ expect(summary.candidates).toBe(1)+ expect(summary.probed).toBe(1)+ expect(summary.admitted).toBe(0)+ expect(summary.skipped.probe_unknown).toBe(1)+ expect(manager.getAllTools()).toEqual([])+ expect(existsCalls).toHaveLength(1)++ // Within backoffMs the probe is paused → the next turn issues no new POST.+ clock += 10_000 // < backoffMs (30s)+ const next = await manager.bootstrapUserCatalog('alice')+ expect(next.skipped.budget_exhausted).toBe(1)+ expect(existsCalls).toHaveLength(1)+ })++ // ── invariant 10 ──+ it('wait budget: a slow admission resolves the bootstrap at ~waitBudgetMs, then lands', async () => {+ const grantStore = new Set(['gh:alice'])+ const { manager, existsCalls } = gatedManager(grantStore, { waitBudgetMs: 40 })+ await manager.addServer(remoteOauthUserServer())++ // Hold the connect open past the wait budget.+ let release!: () => void+ const gate = new Promise<void>(r => (release = r))+ sdk.connectGate = () => gate++ const summary = await manager.bootstrapUserCatalog('alice')+ // The bootstrap did not wait for the admission: it timed out with 1 pending.+ expect(summary.timedOut).toBe(true)+ expect(summary.pending).toBe(1)+ expect(summary.admitted).toBe(0)+ expect(manager.getAllTools()).toEqual([])++ // The admission keeps running; releasing it populates the catalog with NO+ // new probe (the tool loop would pick it up on its next iteration).+ release()+ sdk.connectGate = null+ await vi.waitFor(() => expect(manager.getAllTools().map(t => t.name)).toEqual(['gh__do']))+ expect(existsCalls).toHaveLength(1)+ })++ // ── invariant 11 ──+ it('connect timeout: a hung admission is bounded by connectTimeoutMs, partition not installed', async () => {+ const grantStore = new Set(['gh:alice'])+ // connectTimeoutMs (20ms) fires before the wait budget (400ms).+ const { manager } = gatedManager(grantStore, { connectTimeoutMs: 20, waitBudgetMs: 400 })+ await manager.addServer(remoteOauthUserServer())++ // A connect that never resolves must be aborted by the connect budget.+ sdk.connectGate = () => new Promise<void>(() => {})++ const summary = await manager.bootstrapUserCatalog('alice')+ // The admission failed (timed out) within the wait budget — not left pending.+ expect(summary.timedOut).toBe(false)+ expect(summary.admitted).toBe(0)+ expect(summary.pending).toBe(0)+ expect(summary.skipped.admission_failed).toBe(1)+ // No partition installed.+ expect(manager.getAllTools()).toEqual([])+ })++ // ── signal (§6.5/§7.3): abort cuts the WAIT, never the manager-owned admission ──+ it('aborting the signal ends the wait but never the admission (it lands in background)', async () => {+ const grantStore = new Set(['gh:alice'])+ // Large budgets so the ABORT — not the wait budget or the connect timeout —+ // is what ends the wait, and the admission is never bounded out.+ const { manager, existsCalls } = gatedManager(grantStore, {+ waitBudgetMs: 5000,+ connectTimeoutMs: 5000,+ })+ await manager.addServer(remoteOauthUserServer())++ const controller = new AbortController()+ // Hold the (authenticated) connect open and abort the turn's signal the moment+ // the admission reaches connect — so the abort races an in-flight admission.+ let release!: () => void+ const gate = new Promise<void>(r => (release = r))+ sdk.connectGate = () => {+ controller.abort()+ return gate+ }++ const summary = await manager.bootstrapUserCatalog('alice', { signal: controller.signal })+ // The abort ended the wait exactly like a budget expiry, leaving 1 pending.+ expect(summary.timedOut).toBe(true)+ expect(summary.pending).toBe(1)+ expect(summary.admitted).toBe(0)+ expect(manager.getAllTools()).toEqual([])++ // The admission was NOT aborted: releasing the connect lands the partition+ // with NO new probe, and the catalog reflects it (the tool loop's next pass).+ release()+ sdk.connectGate = null+ await vi.waitFor(() => expect(manager.getAllTools().map(t => t.name)).toEqual(['gh__do']))+ expect(existsCalls).toHaveLength(1)+ })++ // ── snapshot: a background admission failure must not mutate the returned summary ──+ it('the returned summary.skipped is a stable snapshot after the wait budget expires', async () => {+ const grantStore = new Set(['gh:alice'])+ // The wait budget (20ms) expires while the admission is still connecting; the+ // connect timeout (80ms) then fails it AFTER the summary was returned.+ const { manager } = gatedManager(grantStore, { waitBudgetMs: 20, connectTimeoutMs: 80 })+ await manager.addServer(remoteOauthUserServer())+ sdk.connectGate = () => new Promise<void>(() => {}) // hang until connectTimeout fires++ const warnSpy = vi.spyOn(logger, 'warn')+ const summary = await manager.bootstrapUserCatalog('alice')+ expect(summary.timedOut).toBe(true)+ expect(summary.pending).toBe(1)+ // Captured before any admission settled: no failure counted yet.+ expect(summary.skipped.admission_failed).toBeUndefined()++ // The background admission now fails (connect timeout). Its `bump` must land on+ // the manager's live tally, NOT on the frozen object already handed to us.+ await vi.waitFor(() =>+ expect(+ warnSpy.mock.calls.some(+ ([fields]) => fields?.event === 'mcp_catalog_bootstrap_admission_failed'+ )+ ).toBe(true)+ )+ expect(summary.skipped.admission_failed).toBeUndefined()+ warnSpy.mockRestore()+ })++ // ── invariant 13 ──+ it('cap: userPartitionMax reached by another user ⇒ skipped.cap, no POST', async () => {+ const grantStore = new Set(['gh:alice', 'gh:bob'])+ const { manager, existsCalls } = gatedManager(grantStore, {}, undefined, 1)+ await manager.addServer(remoteOauthUserServer())+ // bob's partition fills the cap (via the lazy path — no /grants/exists).+ await manager.callTool('gh__do', {}, { userId: 'bob' })+ expect(existsCalls).toEqual([])++ const summary = await manager.bootstrapUserCatalog('alice')+ expect(summary.candidates).toBe(0)+ expect(summary.skipped.cap).toBe(1)+ expect(existsCalls).toEqual([]) // over the cap → never probed+ })++ // ── invariant 17 ──+ it('kill-switch: enabled:false ⇒ skipped.disabled, no probe, no connect', async () => {+ const grantStore = new Set(['gh:alice'])+ const { manager, existsCalls, userTokenCalls } = gatedManager(grantStore, { enabled: false })+ await manager.addServer(remoteOauthUserServer())++ const summary = await manager.bootstrapUserCatalog('alice')+ expect(summary.skipped.disabled).toBe(1)+ expect(summary.candidates).toBe(0)+ expect(existsCalls).toEqual([])+ expect(userTokenCalls).toEqual([])+ expect(sdk.transports).toEqual([])+ })+})diff --git a/mcp-host/src/mcp/__tests__/managerPartition.test.ts b/mcp-host/src/mcp/__tests__/managerPartition.test.tsindex 637d5e6dc..5c4f9ee28 100644--- a/mcp-host/src/mcp/__tests__/managerPartition.test.ts+++ b/mcp-host/src/mcp/__tests__/managerPartition.test.ts@@ -15,6 +15,8 @@ import fc from 'fast-check'import type { McpServerInfo } from '../../types'import { createBrokerTokenProvider } from '../brokerTokenProvider'import type { McpTokenProvider } from '../client'+import { checkGrantExistence } from '../grantExistenceClient'+import type { GrantExistenceChecker, McpCatalogBootstrapConfig } from '../grantProbe'import {McpManager,type McpPrincipal,@@ -24,6 +26,7 @@ import {serverNameFromClientKey,userPrincipal,} from '../manager'+import { brokerWiring } from './helpers/brokerWiring'// ─── SDK mocks (constructable; capture per-transport headers) ────────────────@@ -688,3 +691,58 @@ describe('R4-M5 — a terminal McpAuthError evicts the per-user partition', () =expect(built.filter(b => b.principal === 'alice')).toHaveLength(2)})})++// ── invariant 14: a bootstrapped partition is idle-evictable and re-bootstraps ──++function remoteOauthUserServer(name = 'gh'): McpServerInfo {+ return {+ name,+ transport: { type: 'streamableHttp', url: `https://${name}.example.com/mcp` },+ authKind: 'oauth-user',+ remote: true,+ enabled: true,+ status: { deployed: true, ready: true },+ }+}++function bootstrapConfig(): McpCatalogBootstrapConfig {+ return {+ enabled: true,+ waitBudgetMs: 4000,+ probeTimeoutMs: 2000,+ connectTimeoutMs: 8000,+ negativeTtlMs: 15000,+ failureTtlMs: 60000,+ probesPerMin: 20,+ backoffMs: 30000,+ }+}++describe('bootstrapped partition interacts with the idle sweep (inv 14)', () => {+ it('is idle-evictable (in partitionLastUsed) and re-bootstraps on the next turn', async () => {+ const grantStore = new Set(['gh:alice'])+ const { deps, factory, existsCalls } = brokerWiring(grantStore)+ const grantExistence: GrantExistenceChecker = (queries, { timeoutMs }) =>+ checkGrantExistence({ ...deps, timeoutMs }, queries)+ const manager = new McpManager(undefined, undefined, factory, {+ grantExistence,+ catalogBootstrap: bootstrapConfig(),+ })+ await manager.addServer(remoteOauthUserServer('gh'))++ // Bootstrap opens the partition without any callTool.+ await manager.bootstrapUserCatalog('alice')+ expect(manager.getAllTools().map(t => t.name)).toEqual(['gh__do'])+ expect(existsCalls).toHaveLength(1)++ // Never called ⇒ its lastUsed is the bootstrap stamp ⇒ idle-evictable.+ expect(manager.evictIdleUserPartitions(0)).toBe(1)+ expect(manager.getAllTools()).toEqual([])++ // The next turn re-probes (it was present, not absent-cached) and re-admits.+ const again = await manager.bootstrapUserCatalog('alice')+ expect(again.admitted).toBe(1)+ expect(existsCalls).toHaveLength(2)+ expect(manager.getAllTools().map(t => t.name)).toEqual(['gh__do'])+ })+})diff --git a/mcp-host/src/mcp/__tests__/managerRemoteOauthCatalog.test.ts b/mcp-host/src/mcp/__tests__/managerRemoteOauthCatalog.test.tsindex 537ec5403..e0cf0a65e 100644--- a/mcp-host/src/mcp/__tests__/managerRemoteOauthCatalog.test.ts+++ b/mcp-host/src/mcp/__tests__/managerRemoteOauthCatalog.test.ts@@ -22,7 +22,10 @@import { beforeEach, describe, expect, it, vi } from 'vitest'import type { McpServerInfo } from '../../types'import type { McpTokenProvider } from '../client'+import { checkGrantExistence } from '../grantExistenceClient'+import type { GrantExistenceChecker, McpCatalogBootstrapConfig } from '../grantProbe'import { McpManager, type McpPrincipal, type McpTokenProviderFactory } from '../manager'+import { brokerWiring } from './helpers/brokerWiring'interface MockTransport {url: string@@ -166,6 +169,39 @@ describe('remote oauth-user catalog is authenticated per-user, never token-lessexpect(sdk.transports[0]!.requestHeaders['Authorization']).toBe('Bearer token-for-alice')expect(manager.getAllTools().map(t => t.name)).toEqual(['remote-gh__do'])})++ // ── (a') sibling: WITH bootstrap, the tool is visible on the first turn ──+ it('bootstrapUserCatalog makes the authenticated tool visible before any callTool', async () => {+ // brokerWiring is the single source of truth (T1): the probe and the token+ // mint read ONE grant store; the file's strict SDK mock is the real upstream.+ const grantStore = new Set(['remote-gh:alice'])+ const { deps, factory, existsCalls } = brokerWiring(grantStore)+ const grantExistence: GrantExistenceChecker = (queries, { timeoutMs }) =>+ checkGrantExistence({ ...deps, timeoutMs }, queries)+ const cfg: McpCatalogBootstrapConfig = {+ enabled: true,+ waitBudgetMs: 4000,+ probeTimeoutMs: 2000,+ connectTimeoutMs: 8000,+ negativeTtlMs: 15000,+ failureTtlMs: 60000,+ probesPerMin: 20,+ backoffMs: 30000,+ }+ const manager = new McpManager(undefined, undefined, factory, {+ grantExistence,+ catalogBootstrap: cfg,+ })+ await manager.addServer(remoteOauthUserServer())++ // No callTool: the bootstrap alone opens the authenticated per-user partition.+ const summary = await manager.bootstrapUserCatalog('alice')+ expect(summary.admitted).toBe(1)+ expect(existsCalls).toEqual([[{ mcpServerName: 'remote-gh', userId: 'alice' }]])+ expect(manager.getAllTools().map(t => t.name)).toEqual(['remote-gh__do'])+ expect(sdk.transports).toHaveLength(1)+ expect(sdk.transports[0]!.requestHeaders['Authorization']).toBe('Bearer tok-alice')+ })})// ─── (b) fail-closed dev: no factory ⇒ no token-less SHARED, no masking catalog ──diff --git a/mcp-host/src/mcp/__tests__/managerSharedGrantGate.test.ts b/mcp-host/src/mcp/__tests__/managerSharedGrantGate.test.tsindex 6c26fe97a..989d4a4ed 100644--- a/mcp-host/src/mcp/__tests__/managerSharedGrantGate.test.ts+++ b/mcp-host/src/mcp/__tests__/managerSharedGrantGate.test.ts@@ -201,6 +201,63 @@ describe('SHARED oauth-context grant gate (spec §6.2)', () => {expect(existsCalls).toEqual([[{ mcpServerName: 'remote-ctx' }]])})+ // ── Fix (coalesce): the bootstrap must not open a SECOND SHARED connection when+ // a discovery poll landed one during the bootstrap's grant probe ──+ it('a bootstrap and a discovery poll racing the SHARED admission open ONE connection', async () => {+ let clock = 1_000+ const grantStore = new Set<string>() // starts without a grant+ const { deps, factory, existsCalls } = brokerWiring(grantStore)++ // Gate ONLY the bootstrap's probe so its SHARED coordinate stays in-flight in+ // the GrantProbe while a discovery poll races the same admission. The discovery+ // poll's probeOne then sees the coordinate in-flight → 'unknown' → fail-open,+ // opening the authenticated SHARED (connection #1). Releasing the bootstrap+ // probe drives it into admitSharedOauthContext for the SAME key: without the+ // admission-time re-check it opens a SECOND connection.+ let releaseProbe!: () => void+ const probeGate = new Promise<void>(r => (releaseProbe = r))+ let armed = false+ const checker: GrantExistenceChecker = async (queries, { timeoutMs }) => {+ if (armed) {+ armed = false+ await probeGate+ }+ return checkGrantExistence({ ...deps, timeoutMs }, queries)+ }+ const manager = new McpManager(undefined, undefined, factory, {+ grantExistence: checker,+ catalogBootstrap: bootstrapConfig(),+ now: () => clock,+ })++ // Register the server while it has no grant → awaiting-grant, no SHARED client.+ await manager.addServer(remoteOauthContextServer())+ expect(sdk.transports).toEqual([])+ // Grant lands; advance past the negative-cache TTL so the probe re-asks.+ grantStore.add('remote-ctx:')+ clock += 16_000++ // Bootstrap parks on the gated probe, holding the SHARED coordinate in-flight.+ armed = true+ const bootstrapPromise = manager.bootstrapUserCatalog('alice')++ // Discovery poll: fails open on the in-flight coordinate and opens connection #1.+ await expect(manager.addServer(remoteOauthContextServer())).resolves.toBe('applied')+ expect(sdk.transports).toHaveLength(1)++ // Release the bootstrap probe: it confirms the grant and reaches the SHARED+ // admission for the SAME key, which it must ADOPT rather than reopen.+ releaseProbe()+ await bootstrapPromise++ // ONE SHARED connection total (the observable §6.5 guarantees), authenticated.+ expect(sdk.transports).toHaveLength(1)+ expect(sdk.transports[0]!.requestHeaders['Authorization']).toBe('Bearer tok-ctx')+ expect(manager.getAllTools().map(t => t.name)).toEqual(['remote-ctx__do'])+ // The discovery poll coalesced onto the bootstrap's probe (no second POST).+ expect(existsCalls).toHaveLength(2) // addServer(no-grant) + bootstrap; discovery deduped+ })+// ── Fix 1: detach must clear the awaiting-grant set (no leak / no log suppression) ──it('detach clears awaiting-grant so a later re-add re-logs the entered transition', async () => {const grantStore = new Set<string>() // no grant → the server stays awaitingdiff --git a/mcp-host/src/mcp/__tests__/selectBootstrapCandidates.property.test.ts b/mcp-host/src/mcp/__tests__/selectBootstrapCandidates.property.test.tsnew file mode 100644index 000000000..02d0d8c02--- /dev/null+++ b/mcp-host/src/mcp/__tests__/selectBootstrapCandidates.property.test.ts@@ -0,0 +1,158 @@+/**+ * Property tests for the PURE bootstrap classifier `selectBootstrapCandidates`+ * (spec §6.1, T2). A fuzz over server flavors, gates, factory presence, live/+ * in-flight keys and the cap explores the M1/M2/M7/M12–M14 precedence that a+ * hand-written case list cannot enumerate. Properties (per §T2):+ * - never a local/static/disabled/not-ready/non-authoritative server;+ * - oauth-context only when a factory is present;+ * - never a live or in-flight key;+ * - never a NEW oauth-user partition at/above the cap;+ * - deterministic; and idempotent — marking the returned keys live yields ∅.+ */+import { describe, expect, it } from 'vitest'+import fc from 'fast-check'+import type { McpServerInfo } from '../../types'+import {+ SHARED_PRINCIPAL,+ selectBootstrapCandidates,+ serializeClientKey,+ userPrincipal,+} from '../manager'++const USER = 'alice'++const arbAuthKind = fc.constantFrom<McpServerInfo['authKind']>(+ 'oauth-user',+ 'oauth-context',+ 'static',+ undefined+)++const arbServer: fc.Arbitrary<McpServerInfo> = fc+ .record({+ name: fc.string({ minLength: 1, maxLength: 6 }).filter(s => !s.includes('"')),+ remote: fc.boolean(),+ authKind: arbAuthKind,+ enabled: fc.boolean(),+ authoritative: fc.option(fc.boolean(), { nil: undefined }),+ ready: fc.boolean(),+ })+ .map(r => ({+ name: r.name,+ transport: { type: 'streamableHttp' as const, url: `https://${r.name || 'x'}.example.com/mcp` },+ authKind: r.authKind,+ remote: r.remote,+ enabled: r.enabled,+ status: { deployed: true, authoritative: r.authoritative, ready: r.ready },+ }))++// Unique by name so each server owns one key (byServer/queries stay 1:1 with it).+const arbServers = fc.uniqueArray(arbServer, {+ maxLength: 6,+ selector: s => s.name,+})++/** The key selectBootstrapCandidates would assign a server (mirrors its logic). */+function keyOf(info: McpServerInfo): string | undefined {+ if (info.authKind === 'oauth-user') return serializeClientKey(info.name, userPrincipal(USER))+ if (info.authKind === 'oauth-context') return serializeClientKey(info.name, SHARED_PRINCIPAL)+ return undefined+}++function gateOk(info: McpServerInfo): boolean {+ return (+ info.enabled === true && info.status?.authoritative !== false && info.status?.ready === true+ )+}++describe('selectBootstrapCandidates — properties (T2)', () => {+ it('only remote oauth, gate-ok, non-live, non-in-flight servers become candidates', () => {+ fc.assert(+ fc.property(+ arbServers,+ fc.boolean(),+ fc.array(fc.nat(), { maxLength: 6 }),+ fc.array(fc.nat(), { maxLength: 6 }),+ (servers, factoryPresent, liveIdx, inflightIdx) => {+ const keys = servers.map(keyOf)+ const live = new Set(liveIdx.map(i => keys[i % Math.max(keys.length, 1)]).filter(Boolean))+ const inflight = new Set(+ inflightIdx.map(i => keys[i % Math.max(keys.length, 1)]).filter(Boolean)+ )+ const sel = selectBootstrapCandidates({+ userId: USER,+ infos: servers,+ hasLive: k => live.has(k),+ hasInFlight: k => inflight.has(k),+ factoryPresent,+ userPartitionCount: 0,+ userPartitionMax: undefined,+ })+ const byName = new Map(servers.map(s => [s.name, s]))+ for (const q of sel.queries) {+ const info = byName.get(q.mcpServerName)!+ expect(info.remote).toBe(true)+ expect(info.authKind === 'oauth-user' || info.authKind === 'oauth-context').toBe(true)+ expect(gateOk(info)).toBe(true)+ if (info.authKind === 'oauth-context') expect(factoryPresent).toBe(true)+ const key = keyOf(info)!+ expect(live.has(key)).toBe(false)+ expect(inflight.has(key)).toBe(false)+ }+ }+ )+ )+ })++ it('at/above the cap, no NEW oauth-user partition is a candidate', () => {+ fc.assert(+ fc.property(+ arbServers,+ fc.integer({ min: 0, max: 5 }),+ fc.integer({ min: 0, max: 5 }),+ (servers, count, max) => {+ const sel = selectBootstrapCandidates({+ userId: USER,+ infos: servers,+ hasLive: () => false,+ hasInFlight: () => false,+ factoryPresent: true,+ userPartitionCount: count,+ userPartitionMax: max,+ })+ const byName = new Map(servers.map(s => [s.name, s]))+ if (count >= max) {+ for (const q of sel.queries) {+ expect(byName.get(q.mcpServerName)!.authKind).not.toBe('oauth-user')+ }+ }+ }+ )+ )+ })++ it('is deterministic and idempotent (marking returned keys live ⇒ second pass empty)', () => {+ fc.assert(+ fc.property(arbServers, fc.boolean(), (servers, factoryPresent) => {+ const base = {+ userId: USER,+ infos: servers,+ hasLive: () => false,+ hasInFlight: () => false,+ factoryPresent,+ userPartitionCount: 0,+ userPartitionMax: undefined as number | undefined,+ }+ const first = selectBootstrapCandidates(base)+ const again = selectBootstrapCandidates(base)+ // Deterministic: same input, same queries.+ expect(again.queries).toEqual(first.queries)++ // Idempotent: once the returned partitions are live, nothing re-qualifies.+ const liveKeys = new Set([...first.byCoord.values()].map(c => c.key))+ const second = selectBootstrapCandidates({ ...base, hasLive: k => liveKeys.has(k) })+ expect(second.queries).toEqual([])+ })+ )+ })+})diff --git a/mcp-host/src/mcp/grantExistenceClient.ts b/mcp-host/src/mcp/grantExistenceClient.tsindex 43d37a118..880d21757 100644--- a/mcp-host/src/mcp/grantExistenceClient.ts+++ b/mcp-host/src/mcp/grantExistenceClient.ts@@ -110,8 +110,16 @@ export async function checkGrantExistence(return data.results as GrantExistsResult[]}-/** Stable coordinate key. `oauth-context` carries no userId → normalized to null. */-function coordKey(mcpServerName: string, userId?: string): string {+/**+ * Canonical grant-coordinate key — the single source of the convention every+ * grant-existence consumer shares (`oauth-context` carries no userId →+ * normalized to null). Exported because this module is BOTH the producer of the+ * coordinate (`buildGrantExistenceQueries`) and of the echoed response the+ * consumers correlate against, so the probe cache, the revocation sweep, and the+ * eager catalog bootstrap all key on the identical string. A second literal copy+ * of it anywhere would break that correlation silently.+ */+export function grantCoordKey(mcpServerName: string, userId?: string): string {return JSON.stringify([mcpServerName, userId ?? null])}@@ -145,11 +153,11 @@ export function selectRevokedPartitionKeys(results: readonly GrantExistsResult[]): string[] {const byCoord = new Map<string, string>()- for (const p of partitions) byCoord.set(coordKey(p.serverName, p.userId), p.key)+ for (const p of partitions) byCoord.set(grantCoordKey(p.serverName, p.userId), p.key)const keys: string[] = []for (const r of results) {if (r.exists !== false) continue- const key = byCoord.get(coordKey(r.mcpServerName, r.userId))+ const key = byCoord.get(grantCoordKey(r.mcpServerName, r.userId))if (key) keys.push(key)}return keysdiff --git a/mcp-host/src/mcp/grantProbe.ts b/mcp-host/src/mcp/grantProbe.tsindex 8c27996b9..64ecbfa9a 100644--- a/mcp-host/src/mcp/grantProbe.ts+++ b/mcp-host/src/mcp/grantProbe.ts@@ -11,11 +11,13 @@** `planProbe` is a PURE function of `(state, now, queries, config)` — it is the* property-tested core; `createGrantProbe` wraps it with the injected HTTP checker- * and the mutable per-manager state. This module deliberately imports NOTHING at- * runtime (config arrives by parameter, the checker is injected) so config.ts can- * import its `McpCatalogBootstrapConfig` type without a cycle.+ * and the mutable per-manager state. Its ONLY runtime import is the canonical+ * `grantCoordKey` from the grant-existence client (the producer of the coordinate+ * this cache keys on — a second copy would diverge silently); config.ts still+ * imports `McpCatalogBootstrapConfig` type-only, so no import cycle forms.*/import type { GrantExistsQuery, GrantExistsResult } from './grantExistenceClient'+import { grantCoordKey } from './grantExistenceClient'/*** The 8 knobs of the eager-bootstrap probe policy. Exported from THIS module (not@@ -95,18 +97,8 @@ const PROBE_WINDOW_MS = 60_000/** control-api caps a single `grants/exists` batch at this many coordinates (routes/mcpOauth.ts). */export const MAX_EXISTS_BATCH = 1000-/**- * Stable coordinate key. MUST match the convention of- * `grantExistenceClient.ts`'s `coordKey`/`selectRevokedPartitionKeys`- * (`oauth-context` carries no userId → normalized to null) so the probe cache- * and the revocation sweep agree on what "a grant" is.- */-function coordKey(mcpServerName: string, userId?: string): string {- return JSON.stringify([mcpServerName, userId ?? null])-}-function coordOf(query: GrantExistsQuery): string {- return coordKey(query.mcpServerName, query.userId)+ return grantCoordKey(query.mcpServerName, query.userId)}export function emptyProbeState(): GrantProbeState {diff --git a/mcp-host/src/mcp/manager.ts b/mcp-host/src/mcp/manager.tsindex 1fdb8a235..4340d497a 100644--- a/mcp-host/src/mcp/manager.ts+++ b/mcp-host/src/mcp/manager.ts@@ -16,6 +16,8 @@ import {type McpToolCallOptions,staticTokenProvider,} from './client'+import type { GrantExistsQuery, GrantExistsResult } from './grantExistenceClient'+import { grantCoordKey } from './grantExistenceClient'import {type GrantExistenceChecker,type GrantProbe,@@ -58,6 +60,93 @@ export interface McpManagerOptions {now?: () => number}+/** Per-turn options for the eager catalog bootstrap (§6.1). */+export interface McpCatalogBootstrapOptions {+ /**+ * Ends this turn's WAIT for its admissions early — the call returns with+ * whatever landed and the rest counted as `pending`, exactly as when the wait+ * budget expires. It does NOT abort the admissions: they are owned by the+ * manager and coalesced (per-user via `ensureInFlight`, SHARED cross-user), so+ * one turn's abort must never tear down a connection another turn/user depends+ * on. §6.1 step 7/M4 mention `signal` on the admission, but §6.5/§7.3 require+ * the abort to leave an in-flight admission running — the latter is the+ * governing reading, so the signal is wired to the wait only.+ */+ signal?: AbortSignal+}++/**+ * Outcome of one `bootstrapUserCatalog` call (§6.1). Every count is a disjoint+ * tally of how a candidate was resolved; `skipped` breaks the non-admitted ones+ * down by reason so the operator can tell a kill-switch (`disabled`) from a+ * budget cap (`budget_exhausted`) from a definitive absence (`absent`).+ */+export interface McpCatalogBootstrapSummary {+ /** Servers that survived the M12–M16 skip gates (i.e. were probe candidates). */+ candidates: number+ /** Coordinates actually sent to the `grants/exists` batch. */+ probed: number+ /** Admissions that resolved within the wait budget. */+ admitted: number+ /** Admissions still in flight when the wait budget expired (they continue). */+ pending: number+ skipped: Partial<+ Record<+ | 'disabled'+ | 'no_user'+ | 'no_factory'+ | 'no_checker'+ | 'manager_closed'+ | 'gate'+ | 'live'+ | 'in_flight'+ | 'cap'+ | 'absent_cached'+ | 'failed_cached'+ | 'budget_exhausted'+ | 'probe_unknown'+ | 'absent'+ | 'admission_failed',+ number+ >+ >+ /** Milliseconds the call waited on admissions. */+ waitedMs: number+ /** The wait budget expired with admissions still pending. */+ timedOut: boolean+}++/** The partition a bootstrap candidate would open, keyed by its grant coordinate. */+export interface BootstrapCandidate {+ key: string+ kind: 'user' | 'shared'+ serverName: string+}++/** Input to the pure `selectBootstrapCandidates` classifier (§6.1). */+export interface SelectBootstrapCandidatesInput {+ userId: string+ infos: Iterable<McpServerInfo>+ /** clients.has — a live partition already exists for the key (M13). */+ hasLive: (key: string) => boolean+ /** ensureInFlight.has || pendingAdmissions.has — an admission is under way (M13). */+ hasInFlight: (key: string) => boolean+ /** A token-provider factory is wired (oauth-context is a candidate only then, M7). */+ factoryPresent: boolean+ /** Live per-user partition count (partitionLastUsed.size) for the cap check (M14). */+ userPartitionCount: number+ /** LRU cap on per-user partitions; undefined disables the cap. */+ userPartitionMax: number | undefined+}++/** Output of `selectBootstrapCandidates`: what to probe and how to correlate it. */+export interface BootstrapCandidateSelection {+ queries: GrantExistsQuery[]+ /** grant coordinate → the partition to open on `exists:true`. */+ byCoord: Map<string, BootstrapCandidate>+ skipped: Partial<Record<'gate' | 'live' | 'in_flight' | 'cap', number>>+}+interface PendingAdmission {attempt: symbolclient: McpClient@@ -166,6 +255,15 @@ export class McpManager {// the SHARED gate (and bootstrap) only engage while enabled. `enabled=false`// ⇒ every rail falls back to today's eager/lazy admission.private readonly catalogBootstrapEnabled: boolean+ // Probe/admission timeouts for bootstrap-initiated connections. Kept alongside+ // grantProbe (which owns the negative-cache/backoff knobs) because the manager+ // — not the probe — owns the wait budget and the per-connection timeout.+ private readonly catalogBootstrap?: McpCatalogBootstrapConfig+ // LRU cap the bootstrap honors so it never thrashes admit→evict above the cap.+ private readonly userPartitionMax?: number+ // Coalesces concurrent bootstraps for the SAME user onto one plan/probe/admit+ // (§6.1 step 2). Cleared on flota reset so a fresh manager starts empty.+ private readonly bootstrapInFlight: Map<string, Promise<McpCatalogBootstrapSummary>> = new Map()// Remote oauth-context servers currently registered WITHOUT an authenticated// SHARED connection (no grant yet). Membership drives the once-per-transition// `mcp_oauth_shared_awaiting_grant` log — discovery re-probes every poll, so@@ -192,6 +290,8 @@ export class McpManager {): undefinedthis.catalogBootstrapEnabled = options?.catalogBootstrap?.enabled ?? false+ this.catalogBootstrap = options?.catalogBootstrap+ this.userPartitionMax = options?.userPartitionMaxif (proxyUrl) {logger.info({ component: 'McpManager' }, 'Proxy mode enabled')}@@ -570,12 +670,47 @@ export class McpManager {*/private admitSharedOauthContext(serverConfig: McpServerInfo,- control: McpAdmissionControl+ control: McpAdmissionControl,+ options?: McpToolCallOptions): Promise<McpAdmissionOutcome> {- this.exitSharedAwaitingGrant(serverConfig.name)const key = this.sharedKey(serverConfig.name)++ // Coalesce at admission time, not only at selection. Both callers — the+ // discovery gate (addGatedSharedOauthContext) and the eager bootstrap —+ // pre-check live/in-flight, then `await` a grant probe (an RTT) before+ // reaching here; in that gap the OTHER caller can land or start the SHARED+ // connection. Without this re-check each would open its own, burning a+ // broker-bucket unit and breaking §6.5's single-SHARED-connection guarantee+ // (pendingAdmissions still fences the double-install, but not the connect).+ // A live representative → adopt it; an in-flight admission → hang off it.+ if (this.clients.has(key)) {+ control.onCommit?.()+ return Promise.resolve('applied')+ }+ const coalesced = this.ensureInFlight.get(key)+ if (coalesced) {+ return coalesced.then(() => {+ if (this.clients.has(key)) {+ control.onCommit?.()+ return 'applied'+ }+ // The admission we adopted settled without a live client (it failed or+ // was superseded). Surface it as a failure so the bootstrap tracker+ // caches it and warns, rather than opening a second connection here.+ throw new Error(`SHARED oauth-context admission did not connect: ${serverConfig.name}`)+ })+ }++ this.exitSharedAwaitingGrant(serverConfig.name)const tokenProvider = this.buildTokenProvider(serverConfig, SHARED_PRINCIPAL, undefined)- const admission = this.connectAndInstall(key, serverConfig, tokenProvider, control, true)+ const admission = this.connectAndInstall(+ key,+ serverConfig,+ tokenProvider,+ control,+ true,+ options+ )const tracked = admission.then(() => undefined,() => undefined@@ -1066,6 +1201,7 @@ export class McpManager {this.partitionLastUsed.clear()this.partitionInFlight.clear()this.sharedAwaitingGrant.clear()+ this.bootstrapInFlight.clear()this.grantProbe?.reset()this.statusTracker.reset()return cleanups@@ -1171,14 +1307,235 @@ export class McpManager {private admissionGate(info: McpServerInfo | undefined): { ok: true } | { ok: false; error: string } {- if (!info?.enabled) {- return { ok: false, error: `MCP server disabled: ${info?.name}` }+ return evaluateAdmissionGate(info)+ }++ /**+ * Eagerly open the remote OAuth partitions this user already has a grant for,+ * so the turn's catalog carries their tools BEFORE the LLM needs them (§6.1) —+ * without a prior failed `callTool`. Idempotent and best-effort: steady-state+ * (every partition already live) costs zero round-trips, a down control-api+ * degrades to today's lazy admission, and a candidate whose admission overruns+ * the wait budget keeps connecting in the background (the tool loop reflects it+ * on its next iteration). Never touches per-serverName status (admissions run+ * with ownsServerStatus=false), never evicts, never probes tools.+ */+ async bootstrapUserCatalog(+ userId: string,+ options: McpCatalogBootstrapOptions = {}+ ): Promise<McpCatalogBootstrapSummary> {+ // Step 1 — total preconditions, each naming its single reason. The three+ // dependency skips stay distinct (a kill-switch is not a missing checker is+ // not a missing factory) so an operator can tell why bootstrap did nothing.+ if (!userId || userId === 'anonymous') return skipAllSummary('no_user')+ if (this.closed) return skipAllSummary('manager_closed')+ if (!this.catalogBootstrapEnabled) return skipAllSummary('disabled')+ if (!this.tokenProviderFactory) return skipAllSummary('no_factory')+ if (!this.grantProbe || !this.catalogBootstrap) return skipAllSummary('no_checker')++ // Step 2 — coalesce concurrent bootstraps of the SAME user onto one run so N+ // simultaneous turns issue one plan/probe and one admission per partition.+ const existing = this.bootstrapInFlight.get(userId)+ if (existing) return existing+ const run = this.runCatalogBootstrap(userId, this.grantProbe, this.catalogBootstrap, options)+ this.bootstrapInFlight.set(userId, run)+ try {+ return await run+ } finally {+ if (this.bootstrapInFlight.get(userId) === run) this.bootstrapInFlight.delete(userId)+ }+ }++ private async runCatalogBootstrap(+ userId: string,+ probe: GrantProbe,+ config: McpCatalogBootstrapConfig,+ options: McpCatalogBootstrapOptions+ ): Promise<McpCatalogBootstrapSummary> {+ const skipped: McpCatalogBootstrapSummary['skipped'] = {}+ const bump = (reason: keyof McpCatalogBootstrapSummary['skipped'], n = 1): void => {+ if (n > 0) skipped[reason] = (skipped[reason] ?? 0) + n+ }++ // Step 3 — classify candidates (pure). serverInfos values are always defined,+ // so the gate inside never sees undefined.+ const selection = selectBootstrapCandidates({+ userId,+ infos: this.serverInfos.values(),+ hasLive: key => this.clients.has(key),+ hasInFlight: key => this.ensureInFlight.has(key) || this.pendingAdmissions.has(key),+ factoryPresent: this.tokenProviderFactory !== undefined,+ userPartitionCount: this.partitionLastUsed.size,+ userPartitionMax: this.userPartitionMax,+ })+ for (const [reason, count] of Object.entries(selection.skipped)) {+ bump(reason as keyof McpCatalogBootstrapSummary['skipped'], count ?? 0)+ }++ const candidates = selection.queries.length+ // Step 4 — nothing to probe (steady-state): zero round-trips, no log.+ if (candidates === 0) {+ return {+ candidates: 0,+ probed: 0,+ admitted: 0,+ pending: 0,+ skipped,+ waitedMs: 0,+ timedOut: false,+ }+ }++ // Steps 5–6 — plan then execute the probe. The plan's non-ask buckets are+ // cache/budget skips; a throw from execute (endpoint down/timeout/429) leaves+ // every asked coordinate unknown — execute already backed off and released+ // its in-flight reservations, so the turn simply proceeds on lazy admission.+ const plan = probe.plan(selection.queries)+ bump('absent_cached', plan.absentCached.length)+ bump('failed_cached', plan.failedCached.length)+ bump('budget_exhausted', plan.budgetExhausted.length)+ bump('in_flight', plan.inFlight.length)+ const probed = plan.ask.length++ let results: GrantExistsResult[]+ try {+ results = await probe.execute(plan.ask)+ } catch {+ bump('probe_unknown', plan.ask.length)+ const summary: McpCatalogBootstrapSummary = {+ candidates,+ probed,+ admitted: 0,+ pending: 0,+ skipped,+ waitedMs: 0,+ timedOut: false,+ }+ this.logBootstrap(summary)+ return summary+ }++ // Step 7 — decide per ASKED coordinate (the authoritative set of what we+ // probed): admit on a confirmed grant, cache a definitive absence, treat a+ // missing / non-boolean result as unknown. Never admit on a malformed datum.+ const resultByCoord = new Map<string, GrantExistsResult>()+ for (const r of results) resultByCoord.set(grantCoordKey(r.mcpServerName, r.userId), r)+ const admissions: Array<{+ coord: string+ candidate: BootstrapCandidate+ promise: Promise<unknown>+ }> = []+ for (const query of plan.ask) {+ const coord = grantCoordKey(query.mcpServerName, query.userId)+ const candidate = selection.byCoord.get(coord)+ const result = resultByCoord.get(coord)+ if (!candidate || !result || typeof result.exists !== 'boolean') {+ bump('probe_unknown')+ continue+ }+ if (result.exists) {+ const promise = this.admitBootstrapCandidate(userId, candidate, config)+ if (promise) admissions.push({ coord, candidate, promise })+ } else {+ probe.recordAbsent(coord)+ bump('absent')+ }}- if (info.status?.authoritative === false || !info.status?.ready) {- const detail = info.status?.message ? ` (${info.status.message})` : ''- return { ok: false, error: `MCP server not ready: ${info.name}${detail}` }++ // Step 9 — per-admission bookkeeping. Runs whenever each admission settles,+ // even after the wait budget expires (the admission is coalesced in+ // ensureInFlight and the loop's next iteration sees it). oauth-user stamps+ // partitionLastUsed so a bootstrapped-but-never-called partition is still+ // idle-evictable (M4). A rejected admission caches the failure (P2) and warns+ // WITHOUT a token or body.+ let admitted = 0+ const pendingCoords = new Set(admissions.map(a => a.coord))+ const tracked = admissions.map(a =>+ a.promise.then(+ () => {+ pendingCoords.delete(a.coord)+ admitted += 1+ if (a.candidate.kind === 'user') this.partitionLastUsed.set(a.candidate.key, Date.now())+ probe.recordAdmissionOk(a.coord)+ },+ (err: unknown) => {+ pendingCoords.delete(a.coord)+ probe.recordAdmissionFailure(a.coord)+ bump('admission_failed')+ logger.warn(+ {+ component: 'McpManager',+ event: 'mcp_catalog_bootstrap_admission_failed',+ serverName: a.candidate.serverName,+ partition: a.candidate.kind === 'user' ? 'per-user' : 'shared',+ err,+ },+ 'MCP catalog bootstrap admission failed'+ )+ }+ )+ )++ // Step 8 — bounded wait: resolve at min(all-settled, waitBudget). Pending+ // admissions keep running; timedOut records that the budget cut the wait.+ const start = Date.now()+ let timedOut = false+ if (tracked.length > 0) {+ timedOut = await raceWithBudget(+ Promise.allSettled(tracked),+ config.waitBudgetMs,+ options.signal+ )+ }++ const summary: McpCatalogBootstrapSummary = {+ candidates,+ probed,+ admitted,+ pending: pendingCoords.size,+ // Snapshot: background admission callbacks (`admission_failed`) keep mutating+ // the live `skipped` after the wait budget/abort frees this summary, so the+ // returned object must not alias the object those callbacks bump.+ skipped: { ...skipped },+ waitedMs: Date.now() - start,+ timedOut,+ }+ // Step 10 — log the summary (candidates > 0 here; steady-state returned above).+ this.logBootstrap(summary)+ return summary+ }++ /**+ * Open one bootstrap candidate's partition, bounded ONLY by connectTimeoutMs+ * (invariant 11) so a bootstrap-initiated connect can never inherit the SDK's+ * ~25-min default and pin a coalesced `ensureInFlight` entry. The turn's+ * `signal` is deliberately NOT threaded here: admissions are owned by the+ * manager and coalesced (per-user via `ensureInFlight`, SHARED cross-user), so+ * one turn's abort must never tear down a connection another turn/user depends+ * on (§6.5/§7.3). The abort instead cuts only THIS turn's wait, in+ * `raceWithBudget`. oauth-user rides the lazy per-user path+ * (ownsServerStatus=false); oauth-context adopts the SHARED admission,+ * coalesced with discovery on the SHARED key.+ */+ private admitBootstrapCandidate(+ userId: string,+ candidate: BootstrapCandidate,+ config: McpCatalogBootstrapConfig+ ): Promise<unknown> | undefined {+ const connectOptions: McpToolCallOptions = { timeoutMs: config.connectTimeoutMs }+ if (candidate.kind === 'user') {+ return this.ensureClient(candidate.serverName, userId, connectOptions)}- return { ok: true }+ const info = this.serverInfos.get(candidate.serverName)+ if (!info) return undefined+ return this.admitSharedOauthContext(info, {}, connectOptions)+ }++ private logBootstrap(summary: McpCatalogBootstrapSummary): void {+ logger.info(+ { component: 'McpManager', event: 'mcp_catalog_bootstrap', ...summary },+ 'MCP catalog bootstrap'+ )}async callTool(@@ -1489,3 +1846,162 @@ export class McpManager {return this.byServer.size > 0}}++/**+ * Fail-closed admission gate (enabled → authoritative → ready), shared by the+ * lazy per-user callTool path (`McpManager.admissionGate`) and the eager+ * bootstrap classifier (`selectBootstrapCandidates`) so the two can never drift+ * (D4). The error strings are load-bearing — `callTool` returns them verbatim.+ */+export function evaluateAdmissionGate(+ info: McpServerInfo | undefined+): { ok: true } | { ok: false; error: string } {+ if (!info?.enabled) {+ return { ok: false, error: `MCP server disabled: ${info?.name}` }+ }+ if (info.status?.authoritative === false || !info.status?.ready) {+ const detail = info.status?.message ? ` (${info.status.message})` : ''+ return { ok: false, error: `MCP server not ready: ${info.name}${detail}` }+ }+ return { ok: true }+}++/**+ * Pure classifier for `bootstrapUserCatalog` (§6.1, tables M1/M2/M7/M12–M14):+ * which remote-oauth servers this user should probe a grant for, keyed by the+ * partition each would open. No I/O, no manager state mutated — property-tested.+ * A local/static server is silently out of scope (M1/M2); every other exclusion+ * is tallied in `skipped`. `oauth-context` is a candidate only with a factory+ * (M7); a live/in-flight partition (M13) or an over-cap per-user admission (M14)+ * is skipped so steady-state yields zero candidates and zero round-trips.+ */+export function selectBootstrapCandidates(+ input: SelectBootstrapCandidatesInput+): BootstrapCandidateSelection {+ const {+ userId,+ infos,+ hasLive,+ hasInFlight,+ factoryPresent,+ userPartitionCount,+ userPartitionMax,+ } = input+ const queries: GrantExistsQuery[] = []+ const byCoord = new Map<string, BootstrapCandidate>()+ const skipped: BootstrapCandidateSelection['skipped'] = {}+ const bump = (reason: keyof BootstrapCandidateSelection['skipped']): void => {+ skipped[reason] = (skipped[reason] ?? 0) + 1+ }++ for (const info of infos) {+ // M1/M2 — only a remote oauth server is a bootstrap candidate.+ if (info.remote !== true) continue+ if (info.authKind !== 'oauth-user' && info.authKind !== 'oauth-context') continue++ // M12 — replicate the lazy callTool admission gate. serverInfos values are+ // always defined, so the gate never degrades to "disabled: undefined".+ if (!evaluateAdmissionGate(info).ok) {+ bump('gate')+ continue+ }++ let key: string+ let kind: 'user' | 'shared'+ let query: GrantExistsQuery+ if (info.authKind === 'oauth-user') {+ key = serializeClientKey(info.name, userPrincipal(userId))+ kind = 'user'+ query = { mcpServerName: info.name, userId }+ } else {+ // M7 — an oauth-context SHARED can authenticate only through the factory.+ if (!factoryPresent) continue+ key = serializeClientKey(info.name, SHARED_PRINCIPAL)+ kind = 'shared'+ query = { mcpServerName: info.name }+ }++ // M13 — idempotency: a live partition or an in-flight admission is not a+ // candidate. Steady-state ⇒ zero candidates ⇒ zero round-trips.+ if (hasLive(key)) {+ bump('live')+ continue+ }+ if (hasInFlight(key)) {+ bump('in_flight')+ continue+ }+ // M14 — cap: never bootstrap a NEW per-user partition above the LRU cap. The+ // lazy callTool path still admits (today's behavior); this only avoids+ // bootstrap-induced admit→evict thrash above the cap.+ if (+ kind === 'user' &&+ userPartitionMax !== undefined &&+ userPartitionCount >= userPartitionMax+ ) {+ bump('cap')+ continue+ }++ queries.push(query)+ byCoord.set(grantCoordKey(info.name, kind === 'user' ? userId : undefined), {+ key,+ kind,+ serverName: info.name,+ })+ }++ return { queries, byCoord, skipped }+}++/** A total-skip summary naming the single precondition that stopped bootstrap. */+function skipAllSummary(+ reason: keyof McpCatalogBootstrapSummary['skipped']+): McpCatalogBootstrapSummary {+ return {+ candidates: 0,+ probed: 0,+ admitted: 0,+ pending: 0,+ skipped: { [reason]: 1 },+ waitedMs: 0,+ timedOut: false,+ }+}++/**+ * Resolve `false` when `settled` (a non-rejecting Promise, e.g.+ * `Promise.allSettled`) resolves first, else `true` when the wait ends early —+ * either `budgetMs` elapses OR `signal` aborts. The loser is left running: the+ * abort (like the budget) cuts only the WAIT, never the manager-owned admissions+ * behind `settled`, which keep connecting in the background (§6.5/§7.3). An+ * already-aborted signal ends the wait on the next tick.+ */+function raceWithBudget(+ settled: Promise<unknown>,+ budgetMs: number,+ signal?: AbortSignal+): Promise<boolean> {+ return new Promise<boolean>(resolve => {+ let done = false+ const finishEarly = (): void => {+ if (done) return+ done = true+ clearTimeout(timer)+ signal?.removeEventListener('abort', finishEarly)+ resolve(true)+ }+ const timer = setTimeout(finishEarly, budgetMs)+ if (signal) {+ if (signal.aborted) queueMicrotask(finishEarly)+ else signal.addEventListener('abort', finishEarly, { once: true })+ }+ void settled.then(() => {+ if (done) return+ done = true+ clearTimeout(timer)+ signal?.removeEventListener('abort', finishEarly)+ resolve(false)+ })+ })+}