Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
feat(mcp-host): defer oversized native tools through discovery
Alfredo Lopezfb84068b33d1
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.jsonindex 6dff9be3d..e27c32cf6 100644--- a/mcp-host/package-lock.json+++ b/mcp-host/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-mcp-host",- "version": "0.1.478",+ "version": "0.1.479","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-mcp-host",- "version": "0.1.478",+ "version": "0.1.479","license": "SEE LICENSE IN LICENSE","dependencies": {"@anthropic-ai/sdk": "^0.32.0",diff --git a/mcp-host/package.json b/mcp-host/package.jsonindex df246a7d9..566043608 100644--- a/mcp-host/package.json+++ b/mcp-host/package.json@@ -1,6 +1,6 @@{"name": "clerum-mcp-host",- "version": "0.1.478",+ "version": "0.1.479","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.tsindex 35c51e850..0a4097e2f 100644--- a/mcp-host/src/agent/__tests__/taskExecutor.test.ts+++ b/mcp-host/src/agent/__tests__/taskExecutor.test.ts@@ -1840,7 +1840,10 @@ describe('TaskExecutor Codex presentation wiring', () => {}const { executor } = makeExecutor('codex-subscription', manager)const { registry, loopController, bridge } = await executor.createToolRegistry()- const initial = await loopController.refreshTools(registry.listDefinitions())+ const fullInitial = registry.listDefinitions()+ const initial = await loopController.refreshTools(fullInitial)+ // #1003 — oversized native generators defer even with zero MCP tools.+ expect(initial.length).toBeLessThan(fullInitial.length)expect(initial.map((t: any) => t.name)).toEqual(expect.arrayContaining(['clerum__tool_search', 'clerum__tool_describe', 'clerum__tool_call']))@@ -1848,7 +1851,7 @@ describe('TaskExecutor Codex presentation wiring', () => {for (const n of [83, 150, 250]) {count = nconst full = registry.listDefinitions()- expect(full).toHaveLength(initial.length + n)+ expect(full).toHaveLength(fullInitial.length + n)expect(JSON.stringify(await loopController.refreshTools(full))).toBe(JSON.stringify(initial))expect(bridge.getDeferrableCatalogNames().size).toBe(n)expect(registry.get(`fixture__tool_${n - 1}`)).not.toBeNull()@@ -1921,6 +1924,7 @@ describe('TaskExecutor Codex presentation wiring', () => {mcpCount: 83,presentedCount: full.length,deferredCount: 0,+ nativeDeferredCount: 0,},'Tool presentation selected')diff --git a/mcp-host/src/agent/taskExecutor.ts b/mcp-host/src/agent/taskExecutor.tsindex abc48c9a7..fbd562dd1 100644--- a/mcp-host/src/agent/taskExecutor.ts+++ b/mcp-host/src/agent/taskExecutor.ts@@ -2162,6 +2162,7 @@ export class TaskExecutor {dynamicToolsEnabled: presentation.bridgeEnabled,codexMode: presentation.codexMode,codexToolDiscoveryBytes: appConfig.codexToolDiscoveryBytes,+ nativeToolDiscoveryBytes: appConfig.nativeToolDiscoveryBytes,dynamicToolsThreshold: appConfig.dynamicToolsThreshold,},{diff --git a/mcp-host/src/capabilities/toolCatalogTools.ts b/mcp-host/src/capabilities/toolCatalogTools.tsindex e7986cfb3..57aa8f095 100644--- a/mcp-host/src/capabilities/toolCatalogTools.ts+++ b/mcp-host/src/capabilities/toolCatalogTools.ts@@ -22,6 +22,14 @@ import type { InternalToolDefinition, InternalToolResult } from '../workflow/typ*/export type CatalogProvider = () => McpTool[]+/** The 3 dynamic-tool-loading bridge tools. They are native and must never be+ * the TARGET of `clerum__tool_call` (LOCKED #11 — no bridge recursion). */+export const BRIDGE_TOOL_NAMES = new Set([+ 'clerum__tool_search',+ 'clerum__tool_describe',+ 'clerum__tool_call',+])+/** Default cap for tool_search results. The model asks for one schema at a* time via tool_describe, so the search result stays a small, schema-free* index even with a 290-tool catalog. */@@ -344,7 +352,8 @@ export function createToolCallTool(): InternalToolDefinition {description:'Invoke a tool discovered via `clerum__tool_search` / `clerum__tool_describe` ' +'by its exact name. Pass the target tool name and its arguments. Use this ' +- 'for tools that are not listed directly; native tools are called directly.',+ 'for tools that are not listed directly, including deferred internal tools. ' ++ 'Tools already listed in `tools[]` are called directly by their own name.',parameters: {type: 'object',properties: {diff --git a/mcp-host/src/config.ts b/mcp-host/src/config.tsindex 66de689af..42152cbbd 100644--- a/mcp-host/src/config.ts+++ b/mcp-host/src/config.ts@@ -9,6 +9,7 @@ import {type CodexToolPresentation,parseCodexToolDiscoveryBytes,parseCodexToolPresentation,+ parseNativeToolDiscoveryBytes,} from './core/orchestration/toolPresentationPolicy'import { ALL_PROVIDERS, type LlmProvider, descriptorFor, isLlmProvider } from './llm/registryCore'import type { McpCatalogBootstrapConfig } from './mcp/grantProbe'@@ -176,6 +177,9 @@ export interface Config {// Codex presentation is independent of the legacy bridge opt-in.codexToolPresentation: CodexToolPresentationcodexToolDiscoveryBytes: number+ // #1003 — Per-native-tool serialized-definition budget; tools above it are+ // presented through discovery while small core tools stay in `tools[]`.+ nativeToolDiscoveryBytes: number// F1 (dynamic-tool-loading) — Gates the dynamic-tool-loading bridge; default// OFF; set true per-host to enable; see// `.specs/dynamic-tool-loading/plan-hermes-bridge.es.md`.@@ -935,6 +939,9 @@ export const config: Config = {// Codex optimization is independent of the legacy dynamic-tools opt-in.codexToolPresentation: parseCodexToolPresentation(process.env.CODEX_TOOL_PRESENTATION),codexToolDiscoveryBytes: parseCodexToolDiscoveryBytes(process.env.CODEX_TOOL_DISCOVERY_BYTES),+ nativeToolDiscoveryBytes: parseNativeToolDiscoveryBytes(+ process.env.CLERUM_NATIVE_TOOL_DISCOVERY_BYTES+ ),// Legacy dynamic tools remain opt-in for other providers.dynamicToolsEnabled: getEnvBool('CLERUM_DYNAMIC_TOOLS_ENABLED', false),// F1 (dynamic-tool-loading) — Minimum deferrable (MCP) tool count above whichdiff --git a/mcp-host/src/core/orchestration/__tests__/approvedToolsLifecycle.integration.test.ts b/mcp-host/src/core/orchestration/__tests__/approvedToolsLifecycle.integration.test.tsindex db4519389..c1833fd11 100644--- a/mcp-host/src/core/orchestration/__tests__/approvedToolsLifecycle.integration.test.ts+++ b/mcp-host/src/core/orchestration/__tests__/approvedToolsLifecycle.integration.test.ts@@ -148,6 +148,26 @@ async function setup(count = 83, reverse = false) {return { manager, native, registry, config, conversation, nativeNames }}+/** #1003 — mirror the controller's size-driven native deferral rule so the+ * integration expectations track the real registry instead of hard-coding+ * which generators are oversized. */+function oversizedNativeNames(+ definitions: Array<{ name: string }>,+ nativeNames: Set<string>+): Set<string> {+ const bridges = new Set(['clerum__tool_search', 'clerum__tool_describe', 'clerum__tool_call'])+ return new Set(+ definitions+ .filter(+ tool =>+ nativeNames.has(tool.name) &&+ !bridges.has(tool.name) &&+ Buffer.byteLength(JSON.stringify(tool), 'utf8') > 2_048+ )+ .map(tool => tool.name)+ )+}+afterEach(async () => {await Promise.all(managers.splice(0).map(manager => manager.close()))remote.catalogs.clear()@@ -197,8 +217,14 @@ describe('approved catalog across presentation and lifecycle', () => {return { presented, parts }}const direct = await buildPrompts()- expect(direct.presented).toEqual(registry.listDefinitions())- expect(direct.presented.some(tool => tool.name === 'alpha__record__read_000')).toBe(true)+ const oversized = oversizedNativeNames(registry.listDefinitions(), nativeNames)+ expect(oversized.size).toBeGreaterThan(0)+ expect(direct.presented).toEqual(+ registry+ .listDefinitions()+ .filter(tool => nativeNames.has(tool.name) && !oversized.has(tool.name))+ )+ expect(direct.presented.some(tool => tool.name === 'alpha__record__read_000')).toBe(false)remote.catalogs.set('late',@@ -239,8 +265,11 @@ describe('approved catalog across presentation and lifecycle', () => {})const presented = await controller.refreshTools(registry.listDefinitions())- expect(presented).toHaveLength(mode === 'direct' ? count + 36 : 36)- expect(presented.filter(tool => nativeNames.has(tool.name))).toHaveLength(36)+ const oversized = oversizedNativeNames(registry.listDefinitions(), nativeNames)+ expect(presented).toHaveLength(mode === 'direct' ? count + 36 : 36 - oversized.size)+ expect(presented.filter(tool => nativeNames.has(tool.name))).toHaveLength(+ mode === 'direct' ? 36 : 36 - oversized.size+ )const target = `alpha__record__read_${String(count % 2 ? count - 1 : count - 2).padStart(3, '0')}`expect(registry.get(target)).not.toBeNull()const call =@@ -289,7 +318,8 @@ describe('approved catalog across presentation and lifecycle', () => {latch)const cold = await auto.refreshTools(registry.listDefinitions())- expect(cold).toHaveLength(36)+ const oversized = oversizedNativeNames(registry.listDefinitions(), nativeNames)+ expect(cold).toHaveLength(36 - oversized.size)remote.catalogs.set('alpha',Array.from({ length: 250 }, (_, i) => ({diff --git a/mcp-host/src/core/orchestration/__tests__/deferrableToolController.test.ts b/mcp-host/src/core/orchestration/__tests__/deferrableToolController.test.tsindex d84ba219c..3fbf22926 100644--- a/mcp-host/src/core/orchestration/__tests__/deferrableToolController.test.ts+++ b/mcp-host/src/core/orchestration/__tests__/deferrableToolController.test.ts@@ -237,6 +237,7 @@ describe('Codex presentation without access limits', () => {mcpCount: 1,presentedCount: all.length,deferredCount: 0,+ nativeDeferredCount: 0,},'Tool presentation selected')@@ -253,6 +254,7 @@ describe('Codex presentation without access limits', () => {mcpCount: 0,presentedCount: native.length,deferredCount: 0,+ nativeDeferredCount: 0,},'Tool presentation selected')@@ -329,3 +331,65 @@ describe('Codex presentation without access limits', () => {expect(latch.get()).toBe(true)})})++describe('#1003 — native tool deferral by serialized size', () => {+ const BRIDGES = ['clerum__tool_search', 'clerum__tool_describe', 'clerum__tool_call']+ const small = tool('shell_exec')+ const oversized = { ...tool('clerum__generate_docx'), description: 'x'.repeat(4096) }+ const nativeNames = new Set([...BRIDGES, small.name, oversized.name])++ function controller(+ mode: 'auto' | 'direct' | 'discovery',+ nativeToolDiscoveryBytes?: number,+ legacy = false+ ) {+ return new DeferrableToolController(+ new DefaultLoopController(),+ nativeNames,+ legacy+ ? { dynamicToolsEnabled: true, dynamicToolsThreshold: 5 }+ : {+ dynamicToolsEnabled: true,+ dynamicToolsThreshold: 60,+ codexMode: mode,+ nativeToolDiscoveryBytes,+ },+ makeLatch()+ )+ }++ it('discovery defers the oversized native but keeps small natives and bridges', async () => {+ const upstream = [small, oversized, ...BRIDGES.map(tool)]+ const out = await controller('discovery', 2048).refreshTools(upstream)+ expect(out.map(t => t.name).sort()).toEqual([...BRIDGES, small.name].sort())+ expect(out.some(t => t.name === oversized.name)).toBe(false)+ })++ it('direct retains the oversized native — no bridge tools means no deferral path', async () => {+ const upstream = [small, oversized]+ expect(await controller('direct', 2048).refreshTools(upstream)).toEqual(upstream)+ })++ it('auto engages from a single oversized native even with zero MCP tools', async () => {+ expect(await controller('auto', 2048).refreshTools([small, oversized])).toEqual([small])+ })++ it('a zero budget disables native deferral without touching MCP policy', async () => {+ const upstream = [small, oversized]+ expect(await controller('discovery', 0).refreshTools(upstream)).toEqual(upstream)+ })++ it('bridge tools stay advertised even when their definition exceeds the budget', async () => {+ const hugeBridge = { ...tool('clerum__tool_call'), description: 'y'.repeat(8192) }+ const upstream = [small, oversized, hugeBridge]+ const out = await controller('discovery', 2048).refreshTools(upstream)+ expect(out.map(t => t.name)).toContain('clerum__tool_call')+ expect(out.some(t => t.name === oversized.name)).toBe(false)+ })++ it('the legacy latched bridge also defers the oversized native', async () => {+ const ctl = controller('discovery', undefined, true)+ const out = await ctl.refreshTools([small, oversized, ...mcpTools(10)])+ expect(out.map(t => t.name)).toEqual([small.name])+ })+})diff --git a/mcp-host/src/core/orchestration/__tests__/toolCallBridge.test.ts b/mcp-host/src/core/orchestration/__tests__/toolCallBridge.test.tsindex d384cf10a..b7d5fb0b8 100644--- a/mcp-host/src/core/orchestration/__tests__/toolCallBridge.test.ts+++ b/mcp-host/src/core/orchestration/__tests__/toolCallBridge.test.ts@@ -298,12 +298,12 @@ describe('clerum__tool_call bridge intercept', () => {expect(real.calls).toHaveLength(0)})- it('rejects recursion: target is a native or another bridge tool', async () => {+ it('rejects recursion into another bridge tool (LOCKED #11)', async () => {const config = makeConfig({tools: {},bridge: bridgeContext(NATIVE, ['server__x']),})- for (const target of ['shell_exec', 'clerum__tool_call', 'clerum__tool_search']) {+ for (const target of ['clerum__tool_call', 'clerum__tool_search', 'clerum__tool_describe']) {const { toolResults } = await executeToolCalls([bridgeCall('c', target, {})], config, 0)expect(toolResults[0].is_error).toBe(true)expect(toolResults[0].tool_call_id).toBe('c')@@ -311,6 +311,36 @@ describe('clerum__tool_call bridge intercept', () => {}})+ it('#1003 unwraps a native target, preserving call.id and executing the real tool', async () => {+ const native = new StubTool('clerum__generate_docx')+ const config = makeConfig({+ tools: { clerum__generate_docx: native },+ bridge: bridgeContext([...NATIVE, 'clerum__generate_docx'], []),+ })+ const { toolResults } = await executeToolCalls(+ [bridgeCall('call-n', 'clerum__generate_docx', { title: 'Report' })],+ config,+ 0+ )+ expect(native.calls).toEqual([{ title: 'Report' }])+ expect(toolResults[0].tool_call_id).toBe('call-n')+ expect(toolResults[0].is_error).toBe(false)+ })++ it('#1003 rejects a native-looking name absent from the native registry', async () => {+ const config = makeConfig({+ tools: {},+ bridge: bridgeContext(NATIVE, ['server__x']),+ })+ const { toolResults } = await executeToolCalls(+ [bridgeCall('c', 'ghost_native_tool', {})],+ config,+ 0+ )+ expect(toolResults[0].is_error).toBe(true)+ expect(toolResults[0].content).toMatch(/not in the current tool catalog/)+ })+it('scope gate rejects an out-of-catalog target without executing', async () => {const real = new StubTool('server__do_thing')const config = makeConfig({diff --git a/mcp-host/src/core/orchestration/__tests__/toolPresentationPolicy.test.ts b/mcp-host/src/core/orchestration/__tests__/toolPresentationPolicy.test.tsindex 9aa350542..bb9a21c33 100644--- a/mcp-host/src/core/orchestration/__tests__/toolPresentationPolicy.test.ts+++ b/mcp-host/src/core/orchestration/__tests__/toolPresentationPolicy.test.ts@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest'import {parseCodexToolDiscoveryBytes,parseCodexToolPresentation,+ parseNativeToolDiscoveryBytes,resolveToolPresentation,} from '../toolPresentationPolicy'@@ -41,6 +42,20 @@ describe('tool presentation configuration', () => {expect(() => parseCodexToolDiscoveryBytes(value)).toThrow('CODEX_TOOL_DISCOVERY_BYTES')})+ it('defaults the native per-tool discovery budget to 2048 bytes', () => {+ expect(parseNativeToolDiscoveryBytes(undefined)).toBe(2_048)+ })+ it.each(['0', '1024', '65536'])('accepts non-negative safe integer %j', value => {+ expect(parseNativeToolDiscoveryBytes(value)).toBe(Number(value))+ })+ it.each(['', '-1', '1.5', '2kb', '9007199254740992'])(+ 'rejects invalid native discovery bytes %j',+ value => {+ expect(() => parseNativeToolDiscoveryBytes(value)).toThrow(+ 'CLERUM_NATIVE_TOOL_DISCOVERY_BYTES'+ )+ }+ )it.each([false, true])('preserves other providers flag %s', enabled => {expect(resolveToolPresentation('zai', {diff --git a/mcp-host/src/core/orchestration/deferrableToolController.ts b/mcp-host/src/core/orchestration/deferrableToolController.tsindex 0b151aee8..02088feb2 100644--- a/mcp-host/src/core/orchestration/deferrableToolController.ts+++ b/mcp-host/src/core/orchestration/deferrableToolController.ts@@ -3,9 +3,11 @@* dynamic-tool-loading "stable bridge" design (Phase F3.1).** When active, it removes all deferrable MCP tools from the advertised- * `tools[]` array, leaving only the native tools (which include the 3 bridge- * tools `clerum__tool_search` / `clerum__tool_describe` / `clerum__tool_call`).- * Deferred MCP tools are reached exclusively through `clerum__tool_call`.+ * `tools[]` array, plus native tools whose serialized definition exceeds the+ * per-tool native discovery budget (#1003 — the document generators dominate+ * per-call token cost). Small native tools and the 3 bridge tools+ * (`clerum__tool_search` / `clerum__tool_describe` / `clerum__tool_call`)+ * always stay advertised; deferred tools are reached through the bridge.** Why a decorator (delegate-first composition): the inner chain* (`ApprovalController → UnifiedApprovalGateController` for interactive tasks,@@ -19,6 +21,7 @@* `isNative` membership is decided by the exact `nativeNames` set (Critical:* `clerum__*` tools contain `__` but are native), NEVER by a string heuristic.*/+import { BRIDGE_TOOL_NAMES } from '../../capabilities/toolCatalogTools'import { logger } from '../../logger'import { LoopController } from '../interfaces'import { ChatMessage, PendingApproval, ToolDefinition } from '../types'@@ -42,6 +45,7 @@ export class DeferrableToolController implements LoopController {private readonly latch: LatchStoreprivate readonly codexMode?: CodexToolPresentationprivate readonly discoveryBytes: number+ private readonly nativeDiscoveryBytes: numberprivate lastPresentation: string | undefinedconstructor(@@ -52,6 +56,7 @@ export class DeferrableToolController implements LoopController {dynamicToolsThreshold: numbercodexMode?: CodexToolPresentationcodexToolDiscoveryBytes?: number+ nativeToolDiscoveryBytes?: number},latch: LatchStore) {@@ -62,6 +67,7 @@ export class DeferrableToolController implements LoopController {this.latch = latchthis.codexMode = config.codexModethis.discoveryBytes = config.codexToolDiscoveryBytes ?? 32_768+ this.nativeDiscoveryBytes = config.nativeToolDiscoveryBytes ?? 2_048}shouldAccept(content: string, iteration: number): boolean {@@ -92,12 +98,18 @@ export class DeferrableToolController implements LoopController {// switches. Never reuse another provider's session latch or promote schemas.if (this.codexMode) {const deferred = upstream.filter(t => !this.nativeNames.has(t.name))+ const deferrableNatives = upstream.filter(t => this.isDeferrableNative(t))+ const deferredNames = new Set([+ ...deferred.map(t => t.name),+ ...deferrableNatives.map(t => t.name),+ ])const discover =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+ Buffer.byteLength(JSON.stringify(deferred), 'utf8') > this.discoveryBytes ||+ deferrableNatives.length > 0)+ const presented = discover ? upstream.filter(t => !deferredNames.has(t.name)) : upstreamconst measurement = {mode: this.codexMode,strategy: discover ? 'discovery' : 'direct',@@ -105,6 +117,7 @@ export class DeferrableToolController implements LoopController {mcpCount: deferred.length,presentedCount: presented.length,deferredCount: discover ? deferred.length : 0,+ nativeDeferredCount: discover ? deferrableNatives.length : 0,}const key = JSON.stringify(measurement)if (key !== this.lastPresentation) {@@ -139,8 +152,24 @@ export class DeferrableToolController implements LoopController {// Passthrough — identical to today's behavior (flag off / under threshold).if (!bridgeActive) return upstream- // STABLE SWAP: advertise ONLY natives (which include the 3 bridge tools).- // Deterministic and session-invariant → `tools[]` byte-stable → cache-safe.- return upstream.filter(t => this.nativeNames.has(t.name))+ // STABLE SWAP: advertise small natives (which include the 3 bridge tools)+ // and defer oversized natives alongside MCP tools. Deterministic and+ // session-invariant → `tools[]` byte-stable → cache-safe.+ return upstream.filter(t => this.nativeNames.has(t.name) && !this.isDeferrableNative(t))+ }++ /**+ * #1003 — a native tool is deferrable when its FULL serialized definition+ * (name + description + parameters — exactly what `tools[]` costs) exceeds+ * the per-tool budget. The decision is size-driven, never name-driven, so+ * core tools stay advertised and no generator is special-cased. The 3+ * bridge tools are exempt regardless of size: they are the access path for+ * everything the swap defers. A budget of 0 disables native deferral.+ */+ private isDeferrableNative(tool: ToolDefinition): boolean {+ if (this.nativeDiscoveryBytes <= 0) return false+ if (BRIDGE_TOOL_NAMES.has(tool.name)) return false+ if (!this.nativeNames.has(tool.name)) return false+ return Buffer.byteLength(JSON.stringify(tool), 'utf8') > this.nativeDiscoveryBytes}}diff --git a/mcp-host/src/core/orchestration/toolPresentationPolicy.ts b/mcp-host/src/core/orchestration/toolPresentationPolicy.tsindex 241c9d93f..cf3162aaa 100644--- a/mcp-host/src/core/orchestration/toolPresentationPolicy.ts+++ b/mcp-host/src/core/orchestration/toolPresentationPolicy.ts@@ -16,6 +16,20 @@ export function parseCodexToolDiscoveryBytes(raw: string | undefined): number {return Number(raw)}+/**+ * Per-native-tool serialized-definition budget. A single native tool whose+ * full definition exceeds this budget is presented through discovery (search ++ * describe + bridge call) instead of `tools[]`. `0` disables native deferral+ * while keeping MCP deferral untouched. Small core tools stay advertised.+ */+export function parseNativeToolDiscoveryBytes(raw: string | undefined): number {+ if (raw === undefined) return 2_048+ if (!/^[0-9]+$/.test(raw) || !Number.isSafeInteger(Number(raw))) {+ throw new Error('CLERUM_NATIVE_TOOL_DISCOVERY_BYTES must be a non-negative safe integer')+ }+ return Number(raw)+}+export function resolveToolPresentation(provider: string,config: { dynamicToolsEnabled: boolean; codexToolPresentation?: CodexToolPresentation },diff --git a/mcp-host/src/core/orchestration/toolUseLoopToolBatch.ts b/mcp-host/src/core/orchestration/toolUseLoopToolBatch.tsindex 2d143948e..f065cc1cb 100644--- a/mcp-host/src/core/orchestration/toolUseLoopToolBatch.ts+++ b/mcp-host/src/core/orchestration/toolUseLoopToolBatch.ts@@ -1,4 +1,5 @@import { randomUUID } from 'crypto'+import { BRIDGE_TOOL_NAMES } from '../../capabilities/toolCatalogTools'import { extractToolIntent, getDisplayName } from '../../progress/intentExtraction.js'import {buildConnectRequiredApproval,@@ -49,14 +50,6 @@ function buildGuardrailSuspension(return { type: 'suspend', approval }}-/** The 3 dynamic-tool-loading bridge tools. They are native and must never be- * the TARGET of `clerum__tool_call` (LOCKED #11 — no recursion). */-const BRIDGE_TOOL_NAMES = new Set([- 'clerum__tool_search',- 'clerum__tool_describe',- 'clerum__tool_call',-])-function bridgeError(call: ToolCall, message: string): ToolResult {// Preserve the original `call.id`/name so the provider pairs the result with// the model's `clerum__tool_call` tool_use block (LOCKED #9).@@ -77,6 +70,10 @@ function bridgeError(call: ToolCall, message: string): ToolResult {* then rewrite to a synthetic `{ id: call.id, name, arguments }` so the* normal gate runs against the REAL tool (Critical #12 validates inner args* against the real schema; LOCKED #10 keys approval on the real name).+ * Native targets are valid destinations (#1003 amendment of LOCKED #11):+ * deferred native tools exist only in the native registry, so membership in+ * `nativeNames` is their scope gate; recursion into a bridge tool stays+ * forbidden.** 2. Direct call to a deferred MCP tool (Critical #9, auto-recover) — a* non-bridge call naming an MCP tool that is currently un-advertised. It is@@ -123,18 +120,33 @@ function resolveBridgeCall(return 'handled'}- // Reject recursion / native targets (LOCKED #11): the bridge targets- // DEFERRABLE MCP tools only.- if (BRIDGE_TOOL_NAMES.has(name) || bridge.nativeNames.has(name)) {+ // Reject recursion (LOCKED #11): a bridge tool must never target another+ // bridge tool, whatever its size or presentation.+ if (BRIDGE_TOOL_NAMES.has(name)) {toolResults.push(bridgeError(call,- `clerum__tool_call cannot target "${name}": native and bridge tools are called directly, not through the bridge.`+ `clerum__tool_call cannot target "${name}": bridge tools cannot invoke one another.`))return 'handled'}+ // #1003 — native target. Deferred native tools are absent from the MCP+ // catalog, so their scope gate is existence in the native registry+ // (`nativeNames`). Rewrite to the real name; the normal gate below then+ // validates and approves the REAL native tool, exactly as a direct call+ // would. Whether the native is currently advertised is irrelevant here —+ // the bridge is just a slower envelope for an advertised tool, never a+ // permission bypass.+ if (bridge.nativeNames.has(name)) {+ return {+ id: call.id,+ name,+ arguments: (innerArgs as Record<string, unknown>) ?? {},+ }+ }+// Scope gate (LOCKED #7, Critical #7): the target must exist in the session's// deferrable catalog. This rejects nonexistent/out-of-catalog names; it is// NOT a per-tool authz boundary (Clerum has no per-tool RBAC).diff --git a/mcp-host/src/core/reasoning/promptBuilder.ts b/mcp-host/src/core/reasoning/promptBuilder.tsindex 932e74f02..0b30ae78b 100644--- a/mcp-host/src/core/reasoning/promptBuilder.ts+++ b/mcp-host/src/core/reasoning/promptBuilder.ts@@ -119,8 +119,8 @@ export const MCP_SERVER_SELECTION_TEXT =export const TOOL_DISCOVERY_TEXT ='Use directly listed tools when available. For additional approved tools, ' +'use `clerum__tool_search` to find them by keyword, `clerum__tool_describe` to ' +- "see one's schema, and `clerum__tool_call` to invoke it. Native tools are " +- 'already available directly. Search narrowly for the current task; refine or page ' ++ "see one's schema, and `clerum__tool_call` to invoke it. This also covers " ++ 'internal tools that are not listed directly. Search narrowly for the current task; refine or page ' +'only when needed rather than loading the whole catalog. Describe only the chosen ' +'tool and reuse its schema from the conversation when available. Each invocation ' +'still checks current permissions and arguments. Do not call tools for tasks that ' +diff --git a/mcp-host/src/core/tools/__tests__/nativeToolRegistry.discoveryCatalog.test.ts b/mcp-host/src/core/tools/__tests__/nativeToolRegistry.discoveryCatalog.test.tsnew file mode 100644index 000000000..567baaa5c--- /dev/null+++ b/mcp-host/src/core/tools/__tests__/nativeToolRegistry.discoveryCatalog.test.ts@@ -0,0 +1,80 @@+import { describe, expect, it } from 'vitest'+import type { McpManager } from '../../../mcp/manager'+import type { NativeToolConfig } from '../../interfaces'+import { NativeToolRegistry } from '../nativeToolRegistry'++const config: NativeToolConfig = {+ workspacePath: '/tmp',+ shellTimeout: 5000,+ toolTimeout: 60000,+ toolProgressInterval: 30000,+ httpAllowlist: [],+ envAllowlist: ['PATH'],+ memoryMaxSize: 1048576,+ statelessLifecycle: false,+}++function stubManager(): McpManager {+ return {+ getAllTools: () => [+ {+ name: 'acme__lookup',+ description: 'Acme lookup',+ inputSchema: { type: 'object' },+ serverName: 'acme',+ },+ ],+ } as unknown as McpManager+}++function buildRegistry(): NativeToolRegistry {+ return new NativeToolRegistry(+ config,+ 'test-conv',+ undefined,+ undefined,+ undefined,+ undefined,+ undefined,+ undefined,+ undefined,+ undefined,+ stubManager(),+ true+ )+}++describe('NativeToolRegistry — #1003 discovery catalog covers natives', () => {+ it('tool_search indexes native tools under server "native" alongside MCP entries', async () => {+ const registry = buildRegistry()+ const search = registry.get('clerum__tool_search')+ expect(search).not.toBeNull()++ const output = await search!.execute({ query: 'shell' })+ expect(output.is_error).toBe(false)+ const payload = JSON.parse(output.content) as {+ results: Array<{ name: string; server: string }>+ }+ const nativeHit = payload.results.find(r => r.name === 'shell_exec')+ expect(nativeHit?.server).toBe('native')+ })++ it('tool_describe returns the full schema of a native tool', async () => {+ const registry = buildRegistry()+ const describe = registry.get('clerum__tool_describe')+ expect(describe).not.toBeNull()++ const output = await describe!.execute({ name: 'shell_exec' })+ expect(output.is_error).toBe(false)+ const payload = JSON.parse(output.content) as {+ found: boolean+ name?: string+ server?: string+ parameters?: Record<string, unknown>+ }+ expect(payload.found).toBe(true)+ expect(payload.name).toBe('shell_exec')+ expect(payload.server).toBe('native')+ expect(payload.parameters).toBeTypeOf('object')+ })+})diff --git a/mcp-host/src/core/tools/nativeToolRegistry.ts b/mcp-host/src/core/tools/nativeToolRegistry.tsindex 368698bde..43d4a690a 100644--- a/mcp-host/src/core/tools/nativeToolRegistry.ts+++ b/mcp-host/src/core/tools/nativeToolRegistry.ts@@ -15,6 +15,7 @@ import { createGfscClient, getGfsToolScopes } from '../../internalTools/gfsClienimport type { LlmProvider } from '../../llm/registryCore'import type { McpManager } from '../../mcp/manager'import type { IncomingMessage } from '../../server'+import type { McpTool } from '../../types'import { getOutputDir, resolveInternalTools } from '../../workflow/internalTools'import type { InternalToolDefinition } from '../../workflow/types'import { ScopedWorkspace } from '../../workspace/scopedWorkspace'@@ -377,8 +378,9 @@ export class NativeToolRegistry implements ToolRegistry {)// F2/F3/F4 (dynamic-tool-loading): read-only discovery meta-tools + the- // execution bridge. They query the live MCP catalog (McpManager.getAllTools())- // on demand and never put schemas into the announced tools[] array.+ // execution bridge. They query the live catalog (MCP tools plus every+ // native definition, #1003) on demand and never put schemas into the+ // announced tools[] array.// Gated on BOTH an McpManager being wired (chat path via taskExecutor; the// tool-name listing registry in main.ts and tests omit it) AND the static// feature flag (LOCKED #5: default OFF, opt-in, small hosts untouched). When@@ -386,7 +388,19 @@ export class NativeToolRegistry implements ToolRegistry {// byte-identical to today and the presence-gated discovery guidance is not// emitted by either prompt path.if (mcpManager && dynamicToolsEnabled) {- const getCatalog = () => mcpManager.getAllTools()+ // #1003 — deferred native tools must be searchable and describable exactly+ // like deferred MCP tools. Native definitions are projected into the+ // catalog shape with serverName "native"; advertised natives appear too so+ // the index stays complete and stable across presentation changes.+ const getCatalog = (): McpTool[] => [+ ...mcpManager.getAllTools(),+ ...this.listDefinitions().map(def => ({+ name: def.name,+ description: def.description,+ inputSchema: def.parameters,+ serverName: 'native',+ })),+ ]this.register(new InternalToolAdapter(createToolSearchTool(getCatalog),