Skip to content

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

TypeScript

fix(mcp-host): preserve direct tool presentation diagnostics

Alfredo Lopez3bef3a40d658
diff --git a/docs/architecture/codex-subscription-transport-contract.md b/docs/architecture/codex-subscription-transport-contract.md
index b70a57d4e..5ce49ad09 100644
--- a/docs/architecture/codex-subscription-transport-contract.md
+++ b/docs/architecture/codex-subscription-transport-contract.md
@@ -185,6 +185,11 @@ Direct retains all definitions subject to the bounded request contract.
Discovery exposes the stable native set and search/describe/call bridge.
The same presentation is usable across a configured failover chain.
+All Codex modes emit the structured `tool-presentation` diagnostic when the
+presentation counts change, including the first refresh. It reports the mode,
+strategy, native/MCP counts and presented/deferred counts without tool definitions.
+Direct mode reports `strategy: direct` and `deferredCount: 0`.
+
Search results contain bounded compact descriptions and no schemas. Follow
`nextOffset` with the same query/filter to continue; explicit `enumerate`
permits full traversal. Describe returns the exact selected schema, never a
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 3e51a6eb4..a485c2635 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.330",
+ "version": "0.1.331",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.330",
+ "version": "0.1.331",
"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 856c5c2a1..75e24cbd9 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.330",
+ "version": "0.1.331",
"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/__tests__/taskExecutor.test.ts b/mcp-host/src/agent/__tests__/taskExecutor.test.ts
index 6c5f5f14e..0b9433dde 100644
--- a/mcp-host/src/agent/__tests__/taskExecutor.test.ts
+++ b/mcp-host/src/agent/__tests__/taskExecutor.test.ts
@@ -3,6 +3,7 @@ import { config as appConfig } from '../../config'
import { ConversationManager } from '../../core/conversation/conversation'
import { LlmError, LlmErrorCode } from '../../core/errors'
import { SimpleEventEmitter } from '../../core/orchestration/eventEmitter'
+import { parseCodexToolPresentation } from '../../core/orchestration/toolPresentationPolicy'
import { executeSingleTool, runToolUseLoop } from '../../core/orchestration/toolUseLoop'
import { TOOL_DISCOVERY_TEXT } from '../../core/reasoning/promptBuilder'
import { registerDesktopTools } from '../../core/tools/desktopTools'
@@ -15,6 +16,7 @@ import { TaskLifecycle } from '../../lifecycle/taskLifecycle'
import { anthropicApiError } from '../../llm/__tests__/sdkErrorFixtures'
import { ClaudeProvider } from '../../llm/claude'
import { PromptCache } from '../../llm/promptCache'
+import { logger } from '../../logger'
import type { Task, TaskError, TaskSource } from '../../queue/types'
import { resolveProviderWorkflowCallerContext } from '../../workflow/providerWorkflowCallerContextClient'
import { TaskExecutor, type TaskExecutorDeps, executionModeForSource } from '../taskExecutor'
@@ -1680,30 +1682,59 @@ describe('TaskExecutor Codex presentation wiring', () => {
expect(registry.get('fixture__tool_249')).not.toBeNull()
})
- it('direct preserves a catalog over32 and does not activate the bridge despite the legacy flag', async () => {
- const previousMode = appConfig.codexToolPresentation
- const previousFlag = appConfig.dynamicToolsEnabled
- appConfig.codexToolPresentation = 'direct'
- appConfig.dynamicToolsEnabled = true
- try {
- const manager = {
- getAllTools: () =>
- Array.from({ length: 83 }, (_, i) => ({
- name: `fixture__tool_${i}`,
- inputSchema: { type: 'object' },
- })),
+ it.each(['codex-subscription', 'zai'])(
+ 'default direct for %s logs the catalog without a bridge',
+ async primary => {
+ const previousMode = appConfig.codexToolPresentation
+ const previousFlag = appConfig.dynamicToolsEnabled
+ const info = vi.spyOn(logger, 'info').mockImplementation(() => {})
+ appConfig.codexToolPresentation = parseCodexToolPresentation(undefined)
+ appConfig.dynamicToolsEnabled = true
+ try {
+ const manager = {
+ getAllTools: () =>
+ Array.from({ length: 83 }, (_, i) => ({
+ name: `fixture__tool_${i}`,
+ inputSchema: { type: 'object' },
+ })),
+ }
+ const { executor, deps } = makeExecutor(primary, manager)
+ if (primary !== 'codex-subscription') {
+ deps.failover = {
+ policy: { fallbacks: [{ provider: 'codex-subscription', model: 'test-model' }] },
+ } as any
+ }
+ const { registry, loopController, bridge } = await executor.createToolRegistry()
+ expect(bridge).toBeUndefined()
+ const full = registry.listDefinitions()
+ expect(full.length).toBeGreaterThan(83)
+ expect(
+ full.filter((tool: any) =>
+ ['clerum__tool_search', 'clerum__tool_describe', 'clerum__tool_call'].includes(
+ tool.name
+ )
+ )
+ ).toEqual([])
+ expect(await loopController.refreshTools(full)).toEqual(full)
+ expect(info).toHaveBeenCalledWith(
+ {
+ component: 'tool-presentation',
+ mode: 'direct',
+ strategy: 'direct',
+ nativeCount: full.length - 83,
+ mcpCount: 83,
+ presentedCount: full.length,
+ deferredCount: 0,
+ },
+ 'Tool presentation selected'
+ )
+ } finally {
+ appConfig.codexToolPresentation = previousMode
+ appConfig.dynamicToolsEnabled = previousFlag
+ info.mockRestore()
}
- const { executor } = makeExecutor('codex-subscription', manager)
- const { registry, loopController, bridge } = await executor.createToolRegistry()
- expect(bridge).toBeUndefined()
- const full = registry.listDefinitions()
- expect(full.length).toBeGreaterThan(83)
- expect(await loopController.refreshTools(full)).toEqual(full)
- } finally {
- appConfig.codexToolPresentation = previousMode
- appConfig.dynamicToolsEnabled = previousFlag
}
- })
+ )
it('rebuilds cached discovery guidance on same-model provider switches, preserving daily snapshot', async () => {
const previous = appConfig.promptCacheEnabled
diff --git a/mcp-host/src/agent/taskExecutor.ts b/mcp-host/src/agent/taskExecutor.ts
index b0320836b..d1d5d5ac7 100644
--- a/mcp-host/src/agent/taskExecutor.ts
+++ b/mcp-host/src/agent/taskExecutor.ts
@@ -1813,7 +1813,8 @@ export class TaskExecutor {
: baseController
const mcpManager = this.deps.mcpManager
- if (!presentation.bridgeEnabled) {
+ // Codex direct still observes the live catalog; observation must not enable discovery.
+ if (!presentation.bridgeEnabled && presentation.codexMode === undefined) {
return { registry: compositeRegistry, loopController: innerController }
}
@@ -1842,20 +1843,21 @@ export class TaskExecutor {
)
// The bridge intercept (executeToolCalls) needs `nativeNames` + the live
- // deferrable catalog. Only wired when an McpManager is present — otherwise
- // there is nothing to defer and the intercept stays inert.
- const bridge: LoopConfig['bridge'] = mcpManager
- ? {
- nativeNames,
- getDeferrableCatalogNames: () =>
- new Set(
- mcpManager
- .getAllTools()
- .map(t => t.name)
- .filter(name => !nativeNames.has(name))
- ),
- }
- : undefined
+ // deferrable catalog. Direct mode observes presentation without installing
+ // discovery interception or registering bridge tools.
+ const bridge: LoopConfig['bridge'] =
+ presentation.bridgeEnabled && mcpManager
+ ? {
+ nativeNames,
+ getDeferrableCatalogNames: () =>
+ new Set(
+ mcpManager
+ .getAllTools()
+ .map(t => t.name)
+ .filter(name => !nativeNames.has(name))
+ ),
+ }
+ : undefined
return { registry: compositeRegistry, loopController, bridge }
}
diff --git a/mcp-host/src/core/orchestration/__tests__/deferrableToolController.test.ts b/mcp-host/src/core/orchestration/__tests__/deferrableToolController.test.ts
index 5e977de42..d84ba219c 100644
--- a/mcp-host/src/core/orchestration/__tests__/deferrableToolController.test.ts
+++ b/mcp-host/src/core/orchestration/__tests__/deferrableToolController.test.ts
@@ -1,4 +1,5 @@
import { describe, expect, it, vi } from 'vitest'
+import { logger } from '../../../logger'
import type { LoopController } from '../../interfaces'
import type { ToolDefinition } from '../../types'
import { DeferrableToolController, type LatchStore } from '../deferrableToolController'
@@ -218,6 +219,49 @@ describe('Codex presentation without access limits', () => {
)
}
+ it('logs live direct counts without serializing schemas or repeating unchanged measurements', async () => {
+ const info = vi.spyOn(logger, 'info').mockImplementation(() => {})
+ // The serialization spy proves direct mode never evaluates the schema byte threshold.
+ const serializeSchema = vi.fn(() => ({ type: 'object' }))
+ const mcp = { ...tool('server__read'), parameters: { toJSON: serializeSchema } }
+ const ctl = controller('direct')
+ const all = [...native, mcp]
+ try {
+ expect(await ctl.refreshTools(all)).toBe(all)
+ expect(info).toHaveBeenCalledExactlyOnceWith(
+ {
+ component: 'tool-presentation',
+ mode: 'direct',
+ strategy: 'direct',
+ nativeCount: native.length,
+ mcpCount: 1,
+ presentedCount: all.length,
+ deferredCount: 0,
+ },
+ 'Tool presentation selected'
+ )
+ expect(await ctl.refreshTools(all)).toBe(all)
+ expect(info).toHaveBeenCalledTimes(1)
+ expect(await ctl.refreshTools(native)).toBe(native)
+ expect(info).toHaveBeenCalledTimes(2)
+ expect(info).toHaveBeenLastCalledWith(
+ {
+ component: 'tool-presentation',
+ mode: 'direct',
+ strategy: 'direct',
+ nativeCount: native.length,
+ mcpCount: 0,
+ presentedCount: native.length,
+ deferredCount: 0,
+ },
+ 'Tool presentation selected'
+ )
+ expect(serializeSchema).not.toHaveBeenCalled()
+ } finally {
+ info.mockRestore()
+ }
+ })
+
it.each([0, 1, 32, 33, 83, 150, 250])(
'direct retains every native and MCP for %i MCP',
async n => {
diff --git a/mcp-host/src/core/orchestration/deferrableToolController.ts b/mcp-host/src/core/orchestration/deferrableToolController.ts
index 41f6499ac..0b151aee8 100644
--- a/mcp-host/src/core/orchestration/deferrableToolController.ts
+++ b/mcp-host/src/core/orchestration/deferrableToolController.ts
@@ -91,12 +91,12 @@ export class DeferrableToolController implements LoopController {
// Codex must reevaluate the live catalog after late connections and provider
// switches. Never reuse another provider's session latch or promote schemas.
if (this.codexMode) {
- if (this.codexMode === 'direct') return upstream
const deferred = upstream.filter(t => !this.nativeNames.has(t.name))
const discover =
- this.codexMode === 'discovery' ||
- deferred.length > this.threshold ||
- Buffer.byteLength(JSON.stringify(deferred), 'utf8') > this.discoveryBytes
+ this.codexMode !== 'direct' &&
+ (this.codexMode === 'discovery' ||
+ deferred.length > this.threshold ||
+ Buffer.byteLength(JSON.stringify(deferred), 'utf8') > this.discoveryBytes)
const presented = discover ? upstream.filter(t => this.nativeNames.has(t.name)) : upstream
const measurement = {
mode: this.codexMode,