Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

fix(mcp-host): address PR #1005 review round 2 findings

Alfredo Lopeze0c3303dcf96
diff --git a/docs/architecture/codex-subscription-transport-contract.md b/docs/architecture/codex-subscription-transport-contract.md
index 7b967cf39..603616338 100644
--- a/docs/architecture/codex-subscription-transport-contract.md
+++ b/docs/architecture/codex-subscription-transport-contract.md
@@ -751,7 +751,8 @@ never targets itself. When an MCP tool and a native share a name, the native win
The native decision runs after the MCP decision and only removes natives, so MCP
tools in `tools[]` are the same for both native modes. When `auto` hides a
native, all 3 bridge tools must be presented; otherwise mcp-host throws instead
-of presenting an unreachable native. In Codex `direct` with native `auto`, the
+of presenting an unreachable native. Wherever dev registers no bridge tools
+(Codex/Grok `direct`, or no MCP manager at all) and native mode is `auto`, the
`tool-presentation` diagnostic counts the 3 bridge tools: `nativeCount` and
`presentedCount` are 3 higher than with native `direct`, and every MCP field is
unchanged. The final list is reported by the separate `native-tool-presentation`
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 660e6c099..a7fba88cd 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.480",
+ "version": "0.1.481",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.480",
+ "version": "0.1.481",
"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 8efd07c91..0724ea0e8 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.480",
+ "version": "0.1.481",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/agent/taskExecutor.ts b/mcp-host/src/agent/taskExecutor.ts
index 3da87f07d..7bdc97c05 100644
--- a/mcp-host/src/agent/taskExecutor.ts
+++ b/mcp-host/src/agent/taskExecutor.ts
@@ -8,6 +8,7 @@
import { randomUUID } from 'node:crypto'
import { snapshotTaskTokenBaseline } from '../budget/taskBrake'
import type { TaskTokenBaseline } from '../budget/taskBrake'
+import { BRIDGE_TOOL_NAMES } from '../capabilities/toolCatalogTools'
import { config as appConfig } from '../config'
import { bindTaskSignal, withAbort } from '../core/adapters/abortableLlmPort'
import { maybeWrapFailover } from '../core/adapters/failoverLlmPort'
@@ -1595,7 +1596,8 @@ export class TaskExecutor {
loopConfig.spilloverStorage = this.deps.spilloverStorage
loopConfig.taskId = this.taskId
// F3 (dynamic-tool-loading): context the `clerum__tool_call` bridge intercept
- // needs in `executeToolCalls`. Undefined when no McpManager is wired.
+ // needs in `executeToolCalls`. Undefined when the registry registered no
+ // bridge tools (no MCP discovery with an McpManager, and native `direct`).
loopConfig.bridge = bridge
// P2 token budgets (§5.2): wire the per-task emergency brake when the P1
// verdict carried a per-task cap AND we captured a start-of-task baseline.
@@ -2158,38 +2160,39 @@ export class TaskExecutor {
const mcpManager = this.deps.mcpManager
// Exact native membership preserves every native/plugin capability.
- const nativeNames = new Set(nativeRegistry.listDefinitions().map(d => d.name))
+ const nativeDefinitions = nativeRegistry.listDefinitions()
+ const nativeNames = new Set(nativeDefinitions.map(d => d.name))
// #1003 — native presentation wraps OUTSIDE the MCP decision on every
// return, so it can only remove natives from the list the MCP presentation
// produced. In `direct` it returns that list unchanged.
const withNativePresentation = (controller: LoopController): LoopController =>
- new NativeToolPresentationController(controller, nativeNames, {
+ new NativeToolPresentationController(controller, nativeDefinitions, {
mode: appConfig.nativeToolPresentation,
discoveryBytes: appConfig.nativeToolDiscoveryBytes,
})
// The bridge intercept (executeToolCalls) needs `nativeNames` + the live
// deferrable catalog. It exists exactly when NativeToolRegistry registered
- // the bridge tools: MCP discovery with an McpManager, or native `auto`.
+ // the bridge tools (MCP discovery with an McpManager, or native `auto`), so
+ // it is derived from the registry rather than repeating that predicate.
// Codex direct with native `direct` observes presentation without
// installing discovery interception or registering bridge tools.
- const bridge: LoopConfig['bridge'] =
- (presentation.bridgeEnabled && mcpManager) || nativeAuto
- ? {
- nativeNames,
- getDeferrableCatalogNames: () =>
- mcpManager
- ? new Set(
- mcpManager
- .getAllTools()
- .map(t => t.name)
- .filter(name => !nativeNames.has(name))
- )
- : new Set<string>(),
- nativeTargets: nativeAuto,
- }
- : undefined
+ const bridge: LoopConfig['bridge'] = [...BRIDGE_TOOL_NAMES].every(name => nativeNames.has(name))
+ ? {
+ nativeNames,
+ getDeferrableCatalogNames: () =>
+ mcpManager
+ ? new Set(
+ mcpManager
+ .getAllTools()
+ .map(t => t.name)
+ .filter(name => !nativeNames.has(name))
+ )
+ : new Set<string>(),
+ nativeTargets: nativeAuto,
+ }
+ : undefined
// Codex direct still observes the live catalog; observation must not enable discovery.
if (!presentation.bridgeEnabled && presentation.codexMode === undefined) {
diff --git a/mcp-host/src/core/orchestration/__tests__/nativeToolPresentation.integration.test.ts b/mcp-host/src/core/orchestration/__tests__/nativeToolPresentation.integration.test.ts
index 86777ce96..baa6fe0a0 100644
--- a/mcp-host/src/core/orchestration/__tests__/nativeToolPresentation.integration.test.ts
+++ b/mcp-host/src/core/orchestration/__tests__/nativeToolPresentation.integration.test.ts
@@ -15,6 +15,7 @@ import { TaskExecutor, type TaskExecutorDeps } from '../../../agent/taskExecutor
import { BRIDGE_TOOL_NAMES } from '../../../capabilities/toolCatalogTools'
import { config as appConfig } from '../../../config'
import { TaskLifecycle } from '../../../lifecycle/taskLifecycle'
+import { PromptCache } from '../../../llm/promptCache'
import type { SingleTurnProvider } from '../../../llm/types'
import { logger } from '../../../logger'
import { McpManager } from '../../../mcp/manager'
@@ -23,7 +24,11 @@ import { ConversationManager } from '../../conversation/conversation'
import { NATIVE_TOOL_DISCOVERY_TEXT, TOOL_DISCOVERY_TEXT } from '../../reasoning/promptBuilder'
import { type ChatMessage, FinishReason, type ToolCall, type ToolDefinition } from '../../types'
import { SimpleEventEmitter } from '../eventEmitter'
-import type { CodexToolPresentation, NativeToolPresentation } from '../toolPresentationPolicy'
+import {
+ type CodexToolPresentation,
+ DEFAULT_NATIVE_TOOL_DISCOVERY_BYTES,
+ type NativeToolPresentation,
+} from '../toolPresentationPolicy'
import { validateToolLinkages } from '../toolUseLoopLinkages'
import { NATIVE_DIRECT_DEV_BASELINE } from './nativeDirectDevBaseline'
@@ -105,6 +110,10 @@ interface Scenario {
/** MCP tool count split over alpha/beta, explicit catalogs, or `null` for no McpManager. */
mcp: number | Record<string, RemoteTool[]> | null
approval?: boolean
+ /** `CLERUM_NATIVE_TOOL_DISCOVERY_BYTES`; the 2048 B default when omitted. */
+ discoveryBytes?: number
+ /** Production default path: tiered prompt parts built and cached per session. */
+ promptCache?: boolean
}
type ProviderCall = { messages: ChatMessage[]; tools: ToolDefinition[] }
type Turn = (call: ProviderCall) => { content?: string; tool_calls?: ToolCall[] }
@@ -171,8 +180,9 @@ async function runScenario(scenario: Scenario, turns: Turn[]) {
codexToolPresentation: scenario.codexMode ?? 'direct',
dynamicToolsEnabled: scenario.legacy === true,
nativeToolPresentation: scenario.native,
+ nativeToolDiscoveryBytes: scenario.discoveryBytes ?? DEFAULT_NATIVE_TOOL_DISCOVERY_BYTES,
contextMaxTokens: 100000,
- promptCacheEnabled: false,
+ promptCacheEnabled: scenario.promptCache === true,
})
const manager =
scenario.mcp === null
@@ -241,11 +251,18 @@ async function runScenario(scenario: Scenario, turns: Turn[]) {
}
const lifecycle = new TaskLifecycle()
lifecycle.register(task)
+ const workspaceService = scenario.promptCache
+ ? {
+ readIdentityFiles: vi.fn(async () => ({ identity: '', soul: '', agents: '', user: '' })),
+ snapshotDailyLogs: vi.fn(async () => 'daily snapshot'),
+ }
+ : undefined
const deps: TaskExecutorDeps = {
conversationManager: new ConversationManager(),
llmProvider: provider,
mcpManager: manager,
- workspaceService: undefined,
+ workspaceService: workspaceService as unknown as TaskExecutorDeps['workspaceService'],
+ promptCache: scenario.promptCache ? new PromptCache() : undefined,
modelName: 'gpt-5.6-luna',
approvalConfig: undefined,
config: {
@@ -265,7 +282,7 @@ async function runScenario(scenario: Scenario, turns: Turn[]) {
}
const executor = new TaskExecutor(task, deps)
await executor.run()
- return { executor, deps, providerCalls, responses }
+ return { executor, deps, providerCalls, responses, workspaceService }
}
/** Search → describe → bridged call for the pptx generator, then a final answer. */
@@ -438,6 +455,64 @@ describe('T1 — native discovery journeys through TaskExecutor.run()', () => {
expect(events('native-tool-presentation')).toEqual([])
expectPptxDelivered(run, 2)
})
+
+ it('the default prompt-cache path carries the native-aware guidance in auto and the dev text in direct', async () => {
+ const run = await runScenario(
+ {
+ provider: 'codex-subscription',
+ codexMode: 'direct',
+ native: 'auto',
+ mcp: 2,
+ promptCache: true,
+ },
+ pptxJourney(NATIVE_TOOL_DISCOVERY_TEXT)
+ )
+ // Witness: the system prompt came from the cached tiered parts, not the legacy builder.
+ expect(run.workspaceService!.snapshotDailyLogs).toHaveBeenCalledTimes(1)
+ expect(systemText(run.providerCalls[0].messages)).toContain('daily snapshot')
+ expectPptxDelivered(run)
+
+ // Same cache path in native direct, with the MCP bridge on: the pre-#1003 text.
+ await Promise.all(managers.splice(0).map(manager => manager.close()))
+ const direct = await runScenario(
+ {
+ provider: 'codex-subscription',
+ codexMode: 'discovery',
+ native: 'direct',
+ mcp: 2,
+ promptCache: true,
+ },
+ [() => ({ content: 'ok' })]
+ )
+ expect(direct.workspaceService!.snapshotDailyLogs).toHaveBeenCalledTimes(1)
+ const directText = systemText(direct.providerCalls[0].messages)
+ expect(directText).toContain(TOOL_DISCOVERY_TEXT)
+ expect(directText).not.toContain(NATIVE_TOOL_DISCOVERY_TEXT)
+ })
+
+ it('CLERUM_NATIVE_TOOL_DISCOVERY_BYTES reaches the controller and decides what is hidden', async () => {
+ const firstTools = async (discoveryBytes: number) => {
+ logEvents.length = 0
+ const run = await runScenario(
+ { provider: 'openai', legacy: false, native: 'auto', mcp: null, discoveryBytes },
+ [() => ({ content: 'ok' })]
+ )
+ expect(run.providerCalls).toHaveLength(1)
+ return names(run.providerCalls[0].tools)
+ }
+ // A budget above every native hides nothing.
+ const roomy = await firstTools(100_000)
+ expect(roomy).toEqual(expect.arrayContaining([...GENERATORS, ...BRIDGE]))
+ expect(events('native-tool-presentation')).toEqual([
+ expect.objectContaining({ budget: 100_000, hiddenNames: [] }),
+ ])
+ // A 1 B budget leaves only the bridge tools.
+ const tight = await firstTools(1)
+ expect(tight.sort()).toEqual(BRIDGE)
+ expect(events('native-tool-presentation')).toEqual([
+ expect.objectContaining({ budget: 1, presentedCount: BRIDGE.length }),
+ ])
+ })
})
describe('T2 — independence matrix (I1, I2 with deviation D1)', () => {
@@ -446,6 +521,8 @@ describe('T2 — independence matrix (I1, I2 with deviation D1)', () => {
{ label: 'codex direct', provider: 'codex-subscription', codexMode: 'direct' },
{ label: 'codex auto', provider: 'codex-subscription', codexMode: 'auto' },
{ label: 'codex discovery', provider: 'codex-subscription', codexMode: 'discovery' },
+ { label: 'grok direct', provider: 'grok-subscription', codexMode: 'direct' },
+ { label: 'grok auto', provider: 'grok-subscription', codexMode: 'auto' },
{ label: 'legacy on', provider: 'openai', legacy: true },
{ label: 'legacy off', provider: 'openai', legacy: false },
]
@@ -454,8 +531,18 @@ describe('T2 — independence matrix (I1, I2 with deviation D1)', () => {
cell.codexMode === 'direct' ||
cell.legacy === false ||
(mcp === 2 && (cell.codexMode === 'auto' || cell.legacy === true))
-
- async function firstTurn(cell: Cell, native: NativeToolPresentation, mcp: number) {
+ /** Whether origin/dev registers the bridge tools: MCP discovery with an McpManager. */
+ const devRegistersBridge = (cell: Cell, mcp: number | null) =>
+ mcp !== null && (cell.legacy === true || (cell.codexMode ?? 'direct') !== 'direct')
+ /**
+ * The non-bridge natives origin/dev presents (pinned by the I4 baseline), so each
+ * matrix cell checks I1 against a fixed reference instead of against other tests.
+ */
+ const DEV_NATIVES = NATIVE_DIRECT_DEV_BASELINE['legacy-off/2'].toolNames
+ .filter(name => !isMcp(name) && !BRIDGE_TOOL_NAMES.has(name))
+ .sort()
+
+ async function firstTurn(cell: Cell, native: NativeToolPresentation, mcp: number | null) {
logEvents.length = 0
const run = await runScenario({ ...cell, native, mcp }, [() => ({ content: 'ok' })])
expect(run.executor.executorState).toBe('completed')
@@ -471,42 +558,41 @@ describe('T2 — independence matrix (I1, I2 with deviation D1)', () => {
return { tools, log }
}
- const nativeSubsets: Record<NativeToolPresentation, string[][]> = { direct: [], auto: [] }
-
for (const cell of cells) {
- for (const mcp of [2, 83]) {
- it(`${cell.label}, ${mcp} MCP: MCP presentation is identical for native direct and auto`, async () => {
+ for (const mcp of [2, 83, null]) {
+ const mcpLabel = mcp === null ? 'no McpManager' : `${mcp} MCP`
+ it(`${cell.label}, ${mcpLabel}: MCP presentation is identical for native direct and auto`, async () => {
const direct = await firstTurn(cell, 'direct', mcp)
const auto = await firstTurn(cell, 'auto', mcp)
// I2 (a): the MCP tools sent to the model are the same list.
const mcpDirect = direct.tools.filter(isMcp)
expect(auto.tools.filter(isMcp)).toEqual(mcpDirect)
- expect(mcpDirect).toHaveLength(devListsMcp(cell, mcp) ? mcp : 0)
+ expect(mcpDirect).toHaveLength(mcp !== null && devListsMcp(cell, mcp) ? mcp : 0)
- // I2 (b)/(c): MCP log fields equal; native counters +3 only in Codex direct.
+ // I2 (b)/(c): MCP log fields equal; native counters +3 exactly where
+ // origin/dev registered no bridge tools (deviation D1).
expect(auto.log.legacy).toEqual(direct.log.legacy)
expect(auto.log.presentation).toHaveLength(direct.log.presentation.length)
direct.log.presentation.forEach((before, index) => {
const after = auto.log.presentation[index]
for (const field of ['mode', 'strategy', 'mcpCount', 'deferredCount'])
expect(after[field]).toBe(before[field])
- const delta = cell.codexMode === 'direct' ? BRIDGE.length : 0
+ const delta = devRegistersBridge(cell, mcp) ? 0 : BRIDGE.length
expect(after.nativeCount).toBe((before.nativeCount as number) + delta)
expect(after.presentedCount).toBe((before.presentedCount as number) + delta)
})
- if (cell.provider === 'codex-subscription') expect(direct.log.presentation).toHaveLength(1)
- if (cell.legacy === true) expect(direct.log.legacy).toHaveLength(1)
+ if (cell.codexMode !== undefined) expect(direct.log.presentation).toHaveLength(1)
+ if (cell.legacy === true && mcp !== null) expect(direct.log.legacy).toHaveLength(1)
// I1: natives depend on native mode only; auto hides exactly the generators.
const nonBridgeNatives = (tools: string[]) =>
tools.filter(name => !isMcp(name) && !BRIDGE_TOOL_NAMES.has(name)).sort()
- nativeSubsets.direct.push(nonBridgeNatives(direct.tools))
- nativeSubsets.auto.push(nonBridgeNatives(auto.tools))
- expect(direct.tools).toEqual(expect.arrayContaining(GENERATORS))
- expect(nonBridgeNatives(direct.tools).filter(name => !auto.tools.includes(name))).toEqual(
- GENERATORS
+ expect(nonBridgeNatives(direct.tools)).toEqual(DEV_NATIVES)
+ expect(nonBridgeNatives(auto.tools)).toEqual(
+ DEV_NATIVES.filter(name => !GENERATORS.includes(name))
)
+ expect(DEV_NATIVES).toEqual(expect.arrayContaining(GENERATORS))
expect(auto.tools).toEqual(expect.arrayContaining(BRIDGE))
expect(direct.log.native).toEqual([])
expect(auto.log.native).toEqual([
@@ -515,14 +601,6 @@ describe('T2 — independence matrix (I1, I2 with deviation D1)', () => {
})
}
}
-
- it('I1: the non-bridge native subset is the same in every MCP cell for each native mode', () => {
- expect(nativeSubsets.direct).toHaveLength(cells.length * 2)
- expect(nativeSubsets.auto).toHaveLength(cells.length * 2)
- for (const mode of ['direct', 'auto'] as const)
- for (const subset of nativeSubsets[mode]) expect(subset).toEqual(nativeSubsets[mode][0])
- expect(nativeSubsets.direct[0].length - nativeSubsets.auto[0].length).toBe(GENERATORS.length)
- })
})
describe('I4 — native direct sends exactly what origin/dev sends', () => {
@@ -533,6 +611,14 @@ describe('I4 — native direct sends exactly what origin/dev sends', () => {
appConfig.nativeTool.workspacePath = savedWorkspacePath
})
+ it('the baseline covers exactly the ten dev cells (a dropped cell cannot pass silently)', () => {
+ expect(Object.keys(NATIVE_DIRECT_DEV_BASELINE).sort()).toEqual(
+ ['codex-auto', 'codex-direct', 'codex-discovery', 'legacy-off', 'legacy-on']
+ .flatMap(label => [`${label}/2`, `${label}/83`])
+ .sort()
+ )
+ })
+
it.each(Object.keys(NATIVE_DIRECT_DEV_BASELINE))(
'%s: tools[] and system prompt are byte-identical to the dev baseline',
async key => {
@@ -716,4 +802,84 @@ describe('T3 — negative guards with liveness witnesses (through TaskExecutor.r
// Witness: the MCP-only name reached MCP, and the colliding name never did.
expect(remote.calls.mock.calls).toEqual([['clerum', { name: 'mcp_only', arguments: {} }]])
})
+
+ it('MCP tools named like the bridge tools never enter the discovery catalog', async () => {
+ // `clerum` + `tool_search` flattens to the native bridge name `clerum__tool_search`.
+ const impostor = (name: string) => ({
+ name,
+ description: `Impostor ${name}`,
+ inputSchema: { type: 'object' },
+ })
+ const catalogs = {
+ clerum: [
+ impostor('tool_search'),
+ impostor('tool_describe'),
+ impostor('tool_call'),
+ {
+ name: 'mcp_only',
+ description: 'MCP only record',
+ inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+ },
+ ],
+ }
+ let listed: string[] = []
+ let described: Record<string, unknown> = {}
+ await runScenario(
+ { provider: 'codex-subscription', codexMode: 'discovery', native: 'auto', mcp: catalogs },
+ [
+ () =>
+ toolCalls(
+ {
+ id: 'enumerate-call',
+ name: 'clerum__tool_search',
+ arguments: { query: '', enumerate: true, server: 'clerum', limit: 50 },
+ },
+ {
+ id: 'describe-call',
+ name: 'clerum__tool_describe',
+ arguments: { name: 'clerum__tool_call' },
+ }
+ ),
+ ({ messages }) => {
+ listed = JSON.parse(toolResult(messages, 'enumerate-call')).results.map(
+ (entry: { name: string }) => entry.name
+ )
+ described = JSON.parse(toolResult(messages, 'describe-call'))
+ return { content: 'done' }
+ },
+ ]
+ )
+ // Witness: the same server's non-colliding tool is listed.
+ expect(listed).toEqual(['clerum__mcp_only'])
+ expect(described).toEqual({ found: false })
+ })
+
+ it('bridge tool descriptions name internal tools only in native auto', async () => {
+ const bridgeDescriptions = async (native: NativeToolPresentation) => {
+ const run = await runScenario(
+ { provider: 'codex-subscription', codexMode: 'discovery', native, mcp: 2 },
+ [() => ({ content: 'ok' })]
+ )
+ await Promise.all(managers.splice(0).map(manager => manager.close()))
+ const tools = run.providerCalls[0].tools
+ const find = (name: string) => {
+ const tool = tools.find(t => t.name === name)
+ if (!tool) throw new Error(`${name} is not presented`)
+ return tool
+ }
+ const search = find('clerum__tool_search').parameters as {
+ properties: { server: { description: string } }
+ }
+ return {
+ call: find('clerum__tool_call').description,
+ server: search.properties.server.description,
+ }
+ }
+ const direct = await bridgeDescriptions('direct')
+ const auto = await bridgeDescriptions('auto')
+ expect(direct.call).toContain('native tools are called directly')
+ expect(direct.server).not.toContain('`native`')
+ expect(auto.call).toContain('including internal tools')
+ expect(auto.server).toContain('`native` for internal tools')
+ })
})
diff --git a/mcp-host/src/core/orchestration/__tests__/nativeToolPresentationController.test.ts b/mcp-host/src/core/orchestration/__tests__/nativeToolPresentationController.test.ts
index 604a395a3..5df7b594f 100644
--- a/mcp-host/src/core/orchestration/__tests__/nativeToolPresentationController.test.ts
+++ b/mcp-host/src/core/orchestration/__tests__/nativeToolPresentationController.test.ts
@@ -14,7 +14,7 @@ const BRIDGE = [...BRIDGE_TOOL_NAMES].map(name => tool(name))
const BIG = tool('clerum__generate_pptx', 3000)
const SMALL = tool('shell_exec')
const MCP_BIG = tool('alpha__huge', 5000)
-const nativeNames = new Set([BIG.name, SMALL.name, ...BRIDGE.map(t => t.name)])
+const nativeDefinitions = [BIG, SMALL, ...BRIDGE]
function delegateReturning(list: ToolDefinition[]) {
const refreshTools = vi.fn(async () => list)
@@ -35,7 +35,7 @@ describe('NativeToolPresentationController', () => {
const upstream = [BIG, SMALL, MCP_BIG]
const { delegate, refreshTools } = delegateReturning(upstream)
const info = vi.spyOn(logger, 'info').mockImplementation(() => {})
- const controller = new NativeToolPresentationController(delegate, nativeNames, {
+ const controller = new NativeToolPresentationController(delegate, nativeDefinitions, {
mode: 'direct',
discoveryBytes: 2048,
})
@@ -48,7 +48,7 @@ describe('NativeToolPresentationController', () => {
it('auto hides only oversized natives and never touches MCP tools', async () => {
const { delegate } = delegateReturning([BIG, SMALL, MCP_BIG, ...BRIDGE])
vi.spyOn(logger, 'info').mockImplementation(() => {})
- const controller = new NativeToolPresentationController(delegate, nativeNames, {
+ const controller = new NativeToolPresentationController(delegate, nativeDefinitions, {
mode: 'auto',
discoveryBytes: 2048,
})
@@ -59,6 +59,21 @@ describe('NativeToolPresentationController', () => {
])
})
+ it('auto measures the native definition, not a same-named MCP definition (I1)', async () => {
+ // An MCP server exposing a tool under a native's name with an oversized schema.
+ const mcpHomonym = tool(SMALL.name, 5000)
+ const { delegate } = delegateReturning([BIG, SMALL, mcpHomonym, ...BRIDGE])
+ vi.spyOn(logger, 'info').mockImplementation(() => {})
+ const controller = new NativeToolPresentationController(delegate, nativeDefinitions, {
+ mode: 'auto',
+ discoveryBytes: 2048,
+ })
+ const names = (await controller.refreshTools([])).map(t => t.name)
+ // Witness: the oversized native generator is hidden in the same refresh.
+ expect(names).not.toContain(BIG.name)
+ expect(names).toContain(SMALL.name)
+ })
+
it('auto throws instead of hiding a native while a bridge tool is missing', async () => {
for (const missing of BRIDGE_TOOL_NAMES) {
const { delegate } = delegateReturning([
@@ -66,7 +81,7 @@ describe('NativeToolPresentationController', () => {
SMALL,
...BRIDGE.filter(t => t.name !== missing),
])
- const controller = new NativeToolPresentationController(delegate, nativeNames, {
+ const controller = new NativeToolPresentationController(delegate, nativeDefinitions, {
mode: 'auto',
discoveryBytes: 2048,
})
@@ -77,7 +92,7 @@ describe('NativeToolPresentationController', () => {
// Witness: the same list with every bridge tool hides the generator.
vi.spyOn(logger, 'info').mockImplementation(() => {})
const { delegate } = delegateReturning([BIG, SMALL, ...BRIDGE])
- const controller = new NativeToolPresentationController(delegate, nativeNames, {
+ const controller = new NativeToolPresentationController(delegate, nativeDefinitions, {
mode: 'auto',
discoveryBytes: 2048,
})
@@ -87,7 +102,7 @@ describe('NativeToolPresentationController', () => {
it('auto without anything to hide does not need the bridge', async () => {
const { delegate } = delegateReturning([SMALL, MCP_BIG])
vi.spyOn(logger, 'info').mockImplementation(() => {})
- const controller = new NativeToolPresentationController(delegate, nativeNames, {
+ const controller = new NativeToolPresentationController(delegate, nativeDefinitions, {
mode: 'auto',
discoveryBytes: 2048,
})
@@ -98,7 +113,7 @@ describe('NativeToolPresentationController', () => {
const list = [BIG, SMALL, ...BRIDGE]
const { delegate, refreshTools } = delegateReturning(list)
const info = vi.spyOn(logger, 'info').mockImplementation(() => {})
- const controller = new NativeToolPresentationController(delegate, nativeNames, {
+ const controller = new NativeToolPresentationController(delegate, nativeDefinitions, {
mode: 'auto',
discoveryBytes: 2048,
})
@@ -127,7 +142,7 @@ describe('NativeToolPresentationController', () => {
it('passes every other hook through to the delegate', () => {
const { delegate } = delegateReturning([])
- const controller = new NativeToolPresentationController(delegate, nativeNames, {
+ const controller = new NativeToolPresentationController(delegate, nativeDefinitions, {
mode: 'auto',
discoveryBytes: 2048,
})
diff --git a/mcp-host/src/core/orchestration/__tests__/nativeToolPresentationPolicy.test.ts b/mcp-host/src/core/orchestration/__tests__/nativeToolPresentationPolicy.test.ts
index 2d08c7e5b..a2ace36cf 100644
--- a/mcp-host/src/core/orchestration/__tests__/nativeToolPresentationPolicy.test.ts
+++ b/mcp-host/src/core/orchestration/__tests__/nativeToolPresentationPolicy.test.ts
@@ -44,7 +44,7 @@ describe('CLERUM_NATIVE_TOOL_PRESENTATION parsing', () => {
it.each(['', ' ', 'AUTO', ' auto', 'discovery', 'off'])('rejects %j', value => {
expect(() => parseNativeToolPresentation(value)).toThrow(
- 'CLERUM_NATIVE_TOOL_PRESENTATION must be direct or auto'
+ `CLERUM_NATIVE_TOOL_PRESENTATION must be direct or auto (got ${JSON.stringify(value)})`
)
})
})
@@ -63,7 +63,7 @@ describe('CLERUM_NATIVE_TOOL_DISCOVERY_BYTES parsing', () => {
'rejects %j',
value => {
expect(() => parseNativeToolDiscoveryBytes(value)).toThrow(
- 'CLERUM_NATIVE_TOOL_DISCOVERY_BYTES must be a positive safe integer'
+ `CLERUM_NATIVE_TOOL_DISCOVERY_BYTES must be a positive safe integer (got ${JSON.stringify(value)})`
)
}
)
@@ -72,15 +72,12 @@ describe('CLERUM_NATIVE_TOOL_DISCOVERY_BYTES parsing', () => {
describe('selectDeferredNatives on the production native registry', () => {
const registry = productionRegistry({ mcpDiscovery: false, nativeDiscovery: true })
const definitions = registry.listDefinitions()
- const nativeNames = new Set(definitions.map(def => def.name))
const bytes = (name: string) =>
Buffer.byteLength(JSON.stringify(definitions.find(def => def.name === name)), 'utf8')
it('hides exactly the five generators at the 2048 B default', () => {
expect(
- [
- ...selectDeferredNatives(definitions, nativeNames, DEFAULT_NATIVE_TOOL_DISCOVERY_BYTES),
- ].sort()
+ [...selectDeferredNatives(definitions, DEFAULT_NATIVE_TOOL_DISCOVERY_BYTES)].sort()
).toEqual([
'clerum__generate_chart',
'clerum__generate_dashboard',
@@ -101,14 +98,12 @@ describe('selectDeferredNatives on the production native registry', () => {
)
})
- it('never selects bridge tools or MCP tools, whatever the budget', () => {
+ it('never selects bridge tools, whatever the budget', () => {
expect(definitions.map(def => def.name)).toEqual(expect.arrayContaining([...BRIDGE_TOOL_NAMES]))
- const mcp = { name: 'alpha__huge', description: 'x'.repeat(10_000), parameters: {} }
- const selected = selectDeferredNatives([...definitions, mcp], nativeNames, 1)
+ const selected = selectDeferredNatives(definitions, 1)
// Witness: a 1 B budget selects every other native.
expect(selected.size).toBe(definitions.length - BRIDGE_TOOL_NAMES.size)
for (const bridge of BRIDGE_TOOL_NAMES) expect(selected.has(bridge)).toBe(false)
- expect(selected.has('alpha__huge')).toBe(false)
})
it('registers no bridge tools without a discovery argument (main.ts tool-name snapshot)', () => {
diff --git a/mcp-host/src/core/orchestration/nativeToolPresentationController.ts b/mcp-host/src/core/orchestration/nativeToolPresentationController.ts
index 503edfc24..3ebc89e7b 100644
--- a/mcp-host/src/core/orchestration/nativeToolPresentationController.ts
+++ b/mcp-host/src/core/orchestration/nativeToolPresentationController.ts
@@ -8,8 +8,10 @@
* MCP decision already produced and never adds or removes an MCP tool.
*
* - `direct`: returns the upstream list unchanged (identity).
- * - `auto`: removes the natives selected by `selectDeferredNatives` (definition
- * larger than the byte budget; bridge tools never selected). Those natives
+ * - `auto`: removes the natives selected by `selectDeferredNatives` over the
+ * native registry's own definitions (definition larger than the byte budget;
+ * bridge tools never selected), so a same-named MCP definition in the
+ * presented list cannot change the selection. Those natives
* stay callable through `clerum__tool_search` / `clerum__tool_describe` /
* `clerum__tool_call`. If any bridge tool is missing from the presented list,
* hiding a native would make it unreachable, so it throws instead.
@@ -22,12 +24,15 @@ import { type NativeToolPresentation, selectDeferredNatives } from './toolPresen
export class NativeToolPresentationController implements LoopController {
private lastPresentation: string | undefined
+ private readonly deferrable: ReadonlySet<string>
constructor(
private readonly delegate: LoopController,
- private readonly nativeNames: ReadonlySet<string>,
+ nativeDefinitions: ReadonlyArray<ToolDefinition>,
private readonly config: { mode: NativeToolPresentation; discoveryBytes: number }
- ) {}
+ ) {
+ this.deferrable = selectDeferredNatives(nativeDefinitions, config.discoveryBytes)
+ }
shouldAccept(content: string, iteration: number): boolean {
return this.delegate.shouldAccept(content, iteration)
@@ -52,7 +57,7 @@ export class NativeToolPresentationController implements LoopController {
const upstream = await this.delegate.refreshTools(currentTools)
if (this.config.mode === 'direct') return upstream
- const hidden = selectDeferredNatives(upstream, this.nativeNames, this.config.discoveryBytes)
+ const hidden = new Set(upstream.map(t => t.name).filter(name => this.deferrable.has(name)))
if (hidden.size > 0) {
const presentedNames = new Set(upstream.map(t => t.name))
const missingBridge = [...BRIDGE_TOOL_NAMES].filter(name => !presentedNames.has(name))
diff --git a/mcp-host/src/core/orchestration/toolPresentationPolicy.ts b/mcp-host/src/core/orchestration/toolPresentationPolicy.ts
index 746f0b1d3..211e18666 100644
--- a/mcp-host/src/core/orchestration/toolPresentationPolicy.ts
+++ b/mcp-host/src/core/orchestration/toolPresentationPolicy.ts
@@ -31,7 +31,9 @@ export type NativeToolPresentation = 'direct' | 'auto'
export function parseNativeToolPresentation(raw: string | undefined): NativeToolPresentation {
if (raw === undefined) return 'direct'
if (raw === 'direct' || raw === 'auto') return raw
- throw new Error('CLERUM_NATIVE_TOOL_PRESENTATION must be direct or auto')
+ throw new Error(
+ `CLERUM_NATIVE_TOOL_PRESENTATION must be direct or auto (got ${JSON.stringify(raw)})`
+ )
}
export const DEFAULT_NATIVE_TOOL_DISCOVERY_BYTES = 2_048
@@ -43,27 +45,32 @@ export const DEFAULT_NATIVE_TOOL_DISCOVERY_BYTES = 2_048
export function parseNativeToolDiscoveryBytes(raw: string | undefined): number {
if (raw === undefined) return DEFAULT_NATIVE_TOOL_DISCOVERY_BYTES
if (!/^[1-9][0-9]*$/.test(raw) || !Number.isSafeInteger(Number(raw))) {
- throw new Error('CLERUM_NATIVE_TOOL_DISCOVERY_BYTES must be a positive safe integer')
+ throw new Error(
+ `CLERUM_NATIVE_TOOL_DISCOVERY_BYTES must be a positive safe integer (got ${JSON.stringify(raw)})`
+ )
}
return Number(raw)
}
/**
* Names of the natives that native `auto` removes from `tools[]`: every native
- * whose FULL serialized definition (name + description + parameters, exactly
- * what `tools[]` costs) exceeds `budget`. Size-driven, never name-driven. The
- * bridge tools are never selected: they are the access path to everything else.
+ * whose serialized definition (`{name, description, parameters}` JSON, the
+ * provider-neutral shape each driver wraps) exceeds `budget`. Size-driven, never
+ * name-driven. The bridge tools are never selected: they are the access path to
+ * everything else.
+ *
+ * `nativeDefinitions` must be the native registry's OWN definitions, never the
+ * presented list: an MCP tool sharing a native's name must not change whether
+ * that native is hidden (I1).
*/
export function selectDeferredNatives(
- definitions: ReadonlyArray<ToolDefinition>,
- nativeNames: ReadonlySet<string>,
+ nativeDefinitions: ReadonlyArray<ToolDefinition>,
budget: number
): Set<string> {
return new Set(
- definitions
+ nativeDefinitions
.filter(
def =>
- nativeNames.has(def.name) &&
!BRIDGE_TOOL_NAMES.has(def.name) &&
Buffer.byteLength(JSON.stringify(def), 'utf8') > budget
)
diff --git a/mcp-host/src/core/orchestration/toolUseLoopToolBatch.ts b/mcp-host/src/core/orchestration/toolUseLoopToolBatch.ts
index 33dd87641..ddea8f351 100644
--- a/mcp-host/src/core/orchestration/toolUseLoopToolBatch.ts
+++ b/mcp-host/src/core/orchestration/toolUseLoopToolBatch.ts
@@ -174,9 +174,11 @@ function resolveBridgeCall(
// preserved id, so the provider pairs it with the model's tool_call block.
//
// The synthetic call (and its eventual ToolResult) intentionally carries the
- // REAL tool name, NOT `clerum__tool_call`. Provider pairing is by
- // `tool_call_id` ONLY, so preserving `call.id` is what matters — do NOT
- // re-mint the id (a fresh id would orphan the model's tool_use block).
+ // REAL tool name, NOT `clerum__tool_call`. Providers pair the result by
+ // `tool_call_id`; drivers whose wire pairs by name (Gemini) resolve the
+ // name from that id against the preceding assistant turn. Preserving
+ // `call.id` is what matters — do NOT re-mint the id (a fresh id would
+ // orphan the model's tool_use block).
return {
id: call.id,
name,
@@ -193,8 +195,9 @@ function resolveBridgeCall(
// catalog == the full MCP universe, so this matches the registry's own
// `Tool not found` — but enforcing the gate explicitly here means a future
// per-host catalog subset cannot be bypassed by a direct call. Native names
- // (and non-MCP names) pass through untouched — they are always advertised and
- // resolved by the native registry. Stateless: nothing is recorded.
+ // (and non-MCP names) pass through untouched — the native registry resolves
+ // them whether or not native `auto` removed them from `tools[]`. Stateless:
+ // nothing is recorded.
//
// The `__` heuristic is safe because of the `serverName__toolName` naming
// invariant (double underscore, see CLAUDE.md): natives are excluded first via
diff --git a/mcp-host/src/core/tools/nativeToolRegistry.ts b/mcp-host/src/core/tools/nativeToolRegistry.ts
index 59c482df8..c172c4a43 100644
--- a/mcp-host/src/core/tools/nativeToolRegistry.ts
+++ b/mcp-host/src/core/tools/nativeToolRegistry.ts
@@ -394,14 +394,16 @@ export class NativeToolRegistry implements ToolRegistry {
// Single catalog. Without native discovery it is exactly the MCP catalog.
// With it (#1003), every non-bridge native is appended under the `native`
// pseudo-server so a deferred native can be searched and described, and
- // MCP entries whose name collides with a native are dropped, because the
- // bridge routes such a name to the native. Read lazily: desktop tools are
- // registered after construction and MCP servers connect late.
+ // MCP entries whose name collides with ANY native (bridge tools included)
+ // are dropped, because the registry routes such a name to the native.
+ // Read lazily: desktop tools are registered after construction and MCP
+ // servers connect late.
const getCatalog = (): McpTool[] => {
const mcpTools = mcpManager?.getAllTools() ?? []
if (!nativeDiscovery) return mcpTools
- const natives = this.listDefinitions().filter(def => !BRIDGE_TOOL_NAMES.has(def.name))
- const nativeNames = new Set(natives.map(def => def.name))
+ const allNatives = this.listDefinitions()
+ const nativeNames = new Set(allNatives.map(def => def.name))
+ const natives = allNatives.filter(def => !BRIDGE_TOOL_NAMES.has(def.name))
return [
...mcpTools.filter(tool => !nativeNames.has(tool.name)),
...natives.map(def => ({
diff --git a/mcp-host/src/llm/drivers/__tests__/googleGenerative.test.ts b/mcp-host/src/llm/drivers/__tests__/googleGenerative.test.ts
index 8d699da2d..a6b9f8b86 100644
--- a/mcp-host/src/llm/drivers/__tests__/googleGenerative.test.ts
+++ b/mcp-host/src/llm/drivers/__tests__/googleGenerative.test.ts
@@ -171,6 +171,67 @@ describe('GoogleGenerativeDriver — tool round-trip', () => {
expect(call.functionCall).toEqual({ name: 'clerum__tool_call', args: bridged })
expect(responses).toEqual(['clerum__tool_call', 'orphan_tool'])
})
+
+ it('names each result after its own turn when the driver reuses call ids across turns', async () => {
+ const callResponse = (name: string) => ({
+ candidates: [
+ { content: { parts: [{ functionCall: { name, args: {} } }] }, finishReason: 'STOP' },
+ ],
+ })
+ const { client, generateContent } = mockClient({
+ candidates: [{ content: { parts: [{ text: 'done' }] }, finishReason: 'STOP' }],
+ })
+ generateContent
+ .mockResolvedValueOnce(callResponse('web_search'))
+ .mockResolvedValueOnce(callResponse('file_read'))
+ const driver = new GoogleGenerativeDriver(client, 'gemini-2.5-pro')
+
+ // Drive three real turns, appending history the way the tool loop does.
+ const history: ChatMessage[] = [{ role: 'user', content: 'research and read' }]
+ const results: Record<string, string> = {
+ web_search: 'search result',
+ file_read: 'file content',
+ }
+ const mintedIds: string[] = []
+ for (let turn = 0; turn < 2; turn++) {
+ const res = await driver.completeSingleTurnWithTools(history, [])
+ const toolCalls = res.tool_calls ?? []
+ expect(toolCalls).toHaveLength(1)
+ mintedIds.push(toolCalls[0].id)
+ history.push({ role: 'assistant', content: '', tool_calls: toolCalls })
+ history.push({
+ role: 'tool',
+ name: toolCalls[0].name,
+ content: results[toolCalls[0].name],
+ tool_call_id: toolCalls[0].id,
+ })
+ }
+ await driver.completeSingleTurnWithTools(history, [])
+
+ // Witness: the driver really minted the same id in both turns.
+ expect(mintedIds).toEqual(['call_0', 'call_0'])
+ const wire = generateContent.mock.calls[2][0].contents.flatMap(
+ (c: {
+ parts: Array<{
+ functionCall?: { name: string }
+ functionResponse?: { name: string; response: { result: string } }
+ }>
+ }) =>
+ c.parts.flatMap(p =>
+ p.functionCall
+ ? [`call:${p.functionCall.name}`]
+ : p.functionResponse
+ ? [`resp:${p.functionResponse.name}=${p.functionResponse.response.result}`]
+ : []
+ )
+ )
+ expect(wire).toEqual([
+ 'call:web_search',
+ 'resp:web_search=search result',
+ 'call:file_read',
+ 'resp:file_read=file content',
+ ])
+ })
})
describe('GoogleGenerativeDriver — finish reasons', () => {
diff --git a/mcp-host/src/llm/drivers/googleGenerative.ts b/mcp-host/src/llm/drivers/googleGenerative.ts
index 6bb88ac4e..3700212ed 100644
--- a/mcp-host/src/llm/drivers/googleGenerative.ts
+++ b/mcp-host/src/llm/drivers/googleGenerative.ts
@@ -148,10 +148,10 @@ export class GoogleGenerativeDriver implements SingleTurnProvider {
const textContent = parts.map(p => p.text ?? '').join('') || null
// Gemini function calls carry no opaque id (it matches responses by name);
- // synthesize a stable per-response id so the normalized ToolCall shape and
- // the downstream tool loop keep working. On the next turn the round-trip
- // recovers the function name from the assistant message we emit (or the
- // tool message's own `name`), so the synthetic id never has to survive.
+ // synthesize a per-response id so the normalized ToolCall shape and the
+ // downstream tool loop keep working. The ids restart at `call_0` on every
+ // response, so they are unique only within one assistant turn; the
+ // round-trip (toGeminiContents) resolves them against that turn alone.
let callIndex = 0
const toolCalls = parts
.filter(p => p.functionCall)
@@ -174,20 +174,15 @@ export class GoogleGenerativeDriver implements SingleTurnProvider {
/**
* Convert the normalized ChatMessage[] into Gemini `contents` + a joined
* `systemInstruction`. Tool results are matched back to their function name
- * via the id→name map built from the assistant tool_calls in the SAME
- * history (Gemini keys function responses by name, not by id).
+ * via the id→name map of the PRECEDING assistant turn (Gemini keys function
+ * responses by name, not by id). The map is per turn because the driver's
+ * synthetic ids restart at `call_0` on every response.
*/
private toGeminiContents(messages: CoreChatMessage[]): {
systemInstruction: string
contents: GeminiContent[]
} {
- const idToName = new Map<string, string>()
- for (const m of messages) {
- if (m.role === 'assistant' && m.tool_calls) {
- for (const tc of m.tool_calls) idToName.set(tc.id, tc.name)
- }
- }
-
+ let turnIdToName = new Map<string, string>()
const systemParts: string[] = []
const contents: GeminiContent[] = []
@@ -199,7 +194,9 @@ export class GoogleGenerativeDriver implements SingleTurnProvider {
if (m.role === 'assistant') {
const parts: GeminiPart[] = []
if (m.content) parts.push({ text: m.content })
+ turnIdToName = new Map()
for (const tc of m.tool_calls ?? []) {
+ turnIdToName.set(tc.id, tc.name)
parts.push({ functionCall: { name: tc.name, args: tc.arguments } })
}
contents.push({ role: 'model', parts: parts.length > 0 ? parts : [{ text: '' }] })
@@ -209,7 +206,8 @@ export class GoogleGenerativeDriver implements SingleTurnProvider {
// The functionCall's own name wins: a call routed through
// `clerum__tool_call` produces a result named after the REAL tool, but
// Gemini pairs the response with the `clerum__tool_call` functionCall.
- const name = (m.tool_call_id ? idToName.get(m.tool_call_id) : undefined) ?? m.name ?? 'tool'
+ const name =
+ (m.tool_call_id ? turnIdToName.get(m.tool_call_id) : undefined) ?? m.name ?? 'tool'
contents.push({
role: 'user',
parts: [{ functionResponse: { name, response: { result: m.content } } }],