Skip to content

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.json
index 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.json
index 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.ts
index 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.ts
index 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 = 200
const 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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-less
expect(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.ts
index 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 awaiting
diff --git a/mcp-host/src/mcp/__tests__/selectBootstrapCandidates.property.test.ts b/mcp-host/src/mcp/__tests__/selectBootstrapCandidates.property.test.ts
new file mode 100644
index 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.ts
index 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 keys
diff --git a/mcp-host/src/mcp/grantProbe.ts b/mcp-host/src/mcp/grantProbe.ts
index 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.ts
index 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: symbol
client: 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 {
)
: undefined
this.catalogBootstrapEnabled = options?.catalogBootstrap?.enabled ?? false
+ this.catalogBootstrap = options?.catalogBootstrap
+ this.userPartitionMax = options?.userPartitionMax
if (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)
+ })
+ })
+}