Skip to content

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

TypeScript

fix(mcp-host): check chat internal-tool arguments against their schema (SEC-002)

marcoteb073b41e968c6
diff --git a/mcp-host/src/core/tools/__tests__/internalToolArguments.test.ts b/mcp-host/src/core/tools/__tests__/internalToolArguments.test.ts
new file mode 100644
index 000000000..a009ed6c5
--- /dev/null
+++ b/mcp-host/src/core/tools/__tests__/internalToolArguments.test.ts
@@ -0,0 +1,149 @@
+// A chat call to an internal tool passes the same schema check as a workflow
+// step before it runs: a call the schema rejects is answered with the reason
+// and creates no folder, file or attachment (SEC-002).
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import * as fs from 'fs'
+import * as os from 'os'
+import * as path from 'path'
+import { workflowValidation } from '../../../workflow/__tests__/support/workflowRouter'
+import { INTERNAL_TOOLS } from '../../../workflow/internalTools'
+import { CALLER_OUTPUTS_DIR } from '../../../workspace/callerOutputs'
+import { resolveCallerRootBinding } from '../../../workspace/callerRootBinding'
+import { ScopedWorkspaceProvider } from '../../../workspace/scopedWorkspace'
+import { NativeToolRegistry } from '../nativeToolRegistry'
+
+// The volume reads as roomy, so the free-space floor never decides these cases.
+vi.mock('fs', async original => {
+ const actual = await original<typeof import('fs')>()
+ return {
+ ...actual,
+ statfsSync: (target: string, options: { bigint: true }) => {
+ const reading = actual.statfsSync(target, options)
+ return { ...reading, blocks: reading.bavail, bfree: reading.bavail }
+ },
+ }
+})
+
+const SHEETS = [{ name: 'S', rows: [['a'], [1]] }]
+
+describe('chat internal-tool arguments are checked before the tool runs', () => {
+ let hostBase: string
+ let provider: ScopedWorkspaceProvider
+ let shared: string
+ const originalOutputDir = process.env.CLERUM_OUTPUT_DIR
+
+ beforeEach(() => {
+ hostBase = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'clerum-chat-args-')))
+ provider = new ScopedWorkspaceProvider(hostBase)
+ // The host's shared folder; chat files never go there.
+ shared = path.join(hostBase, 'outputs')
+ fs.mkdirSync(shared)
+ process.env.CLERUM_OUTPUT_DIR = shared
+ })
+
+ afterEach(() => {
+ if (originalOutputDir === undefined) delete process.env.CLERUM_OUTPUT_DIR
+ else process.env.CLERUM_OUTPUT_DIR = originalOutputDir
+ fs.rmSync(hostBase, { recursive: true, force: true })
+ })
+
+ function callerRoot(): string {
+ const binding = resolveCallerRootBinding(provider, { sender: 'user-a', channelType: 'rpc' })
+ if (!binding.root) throw new Error(`no caller root: ${binding.failureCode}`)
+ return binding.root
+ }
+
+ function chat(root: string, name: string, args: Record<string, unknown>) {
+ const registry = new NativeToolRegistry(
+ {
+ workspacePath: hostBase,
+ shellTimeout: 5000,
+ toolTimeout: 60000,
+ toolProgressInterval: 30000,
+ httpAllowlist: [],
+ envAllowlist: ['PATH'],
+ memoryMaxSize: 1048576,
+ },
+ 'conv-1',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ null,
+ { maxBytes: 52_428_800 },
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ root
+ )
+ return registry.get(name)!.execute(args)
+ }
+
+ const tool = (name: string) => INTERNAL_TOOLS.find(t => t.name === name)!
+
+ it('rejects a filename that is not a string, as a workflow step does, and writes nothing', async () => {
+ const root = callerRoot()
+ const args = { filename: 123, sheets: SHEETS }
+ const result = await chat(root, 'clerum__generate_xlsx', args)
+
+ expect(result.is_error).toBe(true)
+ expect(result.content).toBe('Error: Invalid arguments: data/filename must be string')
+ expect(result.attachments).toBeUndefined()
+ expect(fs.existsSync(path.join(root, CALLER_OUTPUTS_DIR))).toBe(false)
+ expect(fs.readdirSync(shared)).toEqual([])
+ // The same arguments, the same answer on the workflow path.
+ expect(await workflowValidation(tool('clerum__generate_xlsx'), args)).toBe(
+ 'Invalid arguments: data/filename must be string'
+ )
+ })
+
+ it('rejects a missing required field and a value outside an enum before running', async () => {
+ const root = callerRoot()
+ const missing = await chat(root, 'clerum__generate_xlsx', { filename: 'a.xlsx' })
+ expect(missing.content).toBe(
+ "Error: Invalid arguments: data must have required property 'sheets'"
+ )
+ const offEnum = await chat(root, 'clerum__generate_pdf', {
+ filename: 'a.pdf',
+ body: 'x',
+ palette: 'neon',
+ })
+ expect(offEnum.is_error).toBe(true)
+ expect(offEnum.content).toMatch(
+ /^Error: Invalid arguments: data\/palette must be equal to one of the allowed values/
+ )
+ expect(fs.existsSync(path.join(root, CALLER_OUTPUTS_DIR))).toBe(false)
+ })
+
+ it('names a few problems of a call that breaks many fields, not all of them', async () => {
+ const root = callerRoot()
+ const sheets = Array.from({ length: 40 }, () => ({ name: 7, rows: 'none' }))
+ const result = await chat(root, 'clerum__generate_xlsx', { filename: 'a.xlsx', sheets })
+ expect(result.is_error).toBe(true)
+ expect(result.content).toMatch(/; and \d+ more$/)
+ expect(result.content.length).toBeLessThanOrEqual('Error: Invalid arguments: '.length + 1_001)
+ })
+
+ it('still makes and delivers the file of a valid call from the caller folder', async () => {
+ const root = callerRoot()
+ // A null for an unset optional argument is still read as unset.
+ const result = await chat(root, 'clerum__generate_xlsx', {
+ filename: 'ok.xlsx',
+ sheets: SHEETS,
+ branding: null,
+ })
+ expect(result.is_error, result.content).toBe(false)
+ expect(fs.readdirSync(path.join(root, CALLER_OUTPUTS_DIR))).toEqual(['ok.xlsx'])
+ expect(result.attachments).toHaveLength(1)
+ expect(result.attachments![0]).toMatchObject({ sourceTool: 'clerum__generate_xlsx' })
+ expect(
+ await workflowValidation(tool('clerum__generate_xlsx'), {
+ filename: 'ok.xlsx',
+ sheets: SHEETS,
+ })
+ ).toBe(true)
+ })
+})
diff --git a/mcp-host/src/core/tools/nativeToolRegistry.ts b/mcp-host/src/core/tools/nativeToolRegistry.ts
index 58d74ab1b..8f0fabb7e 100644
--- a/mcp-host/src/core/tools/nativeToolRegistry.ts
+++ b/mcp-host/src/core/tools/nativeToolRegistry.ts
@@ -20,6 +20,7 @@ import type { LlmProvider } from '../../llm/registryCore'
import type { McpManager } from '../../mcp/manager'
import type { IncomingMessage } from '../../server'
import type { McpTool } from '../../types'
+import { checkToolArguments } from '../../workflow/argumentGate'
import { resolveInternalTools } from '../../workflow/internalTools'
import { boilerplateTexts } from '../../workflow/officeBoilerplate'
import { printedForms } from '../../workflow/toolText'
@@ -115,6 +116,12 @@ class InternalToolAdapter implements Tool {
}
async execute(params: Record<string, unknown>, context?: ExecutionContext): Promise<ToolOutput> {
const start = Date.now()
+ // The schema check a workflow step runs, before anything is resolved or
+ // written: a call it rejects creates no folder, file or attachment.
+ const checked = checkToolArguments(this.def, params)
+ if (!checked.ok) {
+ return { content: `Error: ${checked.error}`, duration_ms: Date.now() - start, is_error: true }
+ }
let outputDir = this.outputDir
if (this.callerOutputs) {
const resolved = this.callerOutputs()
@@ -129,7 +136,7 @@ class InternalToolAdapter implements Tool {
outputDir = resolved.dir
}
try {
- const result = await this.def.execute(params, outputDir, {
+ const result = await this.def.execute(checked.input, outputDir, {
signal: context?.signal,
timeoutMs: context?.timeoutMs,
visualInput: context?.visualInput,
diff --git a/mcp-host/src/workflow/argumentGate.ts b/mcp-host/src/workflow/argumentGate.ts
new file mode 100644
index 000000000..4f26c7ca1
--- /dev/null
+++ b/mcp-host/src/workflow/argumentGate.ts
@@ -0,0 +1,65 @@
+/**
+ * The check every internal tool call passes before it runs, from chat and from
+ * a workflow step alike: nulls sent for unset optional arguments are dropped,
+ * then the arguments are validated against the tool's JSON Schema. A call that
+ * fails runs nothing, so it writes no file and attaches nothing.
+ */
+import Ajv, { type ErrorObject, type ValidateFunction } from 'ajv'
+import { logger } from '../logger'
+import { withoutUnsetNulls } from './schemaArguments'
+import type { InternalToolDefinition } from './types'
+
+const ajv = new Ajv({ allErrors: true, strict: false, useDefaults: true })
+const compiled = new WeakMap<object, ValidateFunction | null>()
+
+/**
+ * A call can break every field of a long document at once; naming a few is
+ * enough for the model to fix the call, and keeps the error out of its way.
+ */
+const MAX_ERRORS = 8
+const MAX_ERROR_CHARS = 1_000
+
+/**
+ * The validator of `tool`'s schema, compiled once per schema. A schema that
+ * does not compile is logged and leaves the tool's own argument checks.
+ */
+export function argumentValidator(tool: InternalToolDefinition): ValidateFunction | null {
+ const schema = tool.parameters
+ const known = compiled.get(schema)
+ if (known !== undefined) return known
+ let validator: ValidateFunction | null = null
+ try {
+ validator = ajv.compile(schema)
+ } catch (err) {
+ // Surface the failure so a schema regression does not pass silently.
+ logger.warn({ err, toolName: tool.name }, 'Internal tool schema compilation failed')
+ }
+ compiled.set(schema, validator)
+ return validator
+}
+
+function errorsText(errors: ErrorObject[] | null | undefined): string {
+ const all = errors ?? []
+ let text = ajv.errorsText(all.slice(0, MAX_ERRORS), { separator: '; ' })
+ if (all.length > MAX_ERRORS) text += `; and ${all.length - MAX_ERRORS} more`
+ return text.length > MAX_ERROR_CHARS ? `${text.slice(0, MAX_ERROR_CHARS)}…` : text
+}
+
+export type ArgumentCheck =
+ | { ok: true; input: Record<string, unknown> }
+ | { ok: false; error: string }
+
+/**
+ * `args` as `tool` runs them, with the schema's defaults filled in, or why it
+ * must not run. The objects the schema describes are copied before defaults
+ * are filled, so `args` stays as sent.
+ */
+export function checkToolArguments(
+ tool: InternalToolDefinition,
+ args: Record<string, unknown> | null | undefined
+): ArgumentCheck {
+ const input = withoutUnsetNulls(tool.parameters, args ?? {}) as Record<string, unknown>
+ const validate = argumentValidator(tool)
+ if (!validate || validate(input)) return { ok: true, input }
+ return { ok: false, error: `Invalid arguments: ${errorsText(validate.errors)}` }
+}
diff --git a/mcp-host/src/workflow/stepRouter.ts b/mcp-host/src/workflow/stepRouter.ts
index d2dbf1913..13a0edd6d 100644
--- a/mcp-host/src/workflow/stepRouter.ts
+++ b/mcp-host/src/workflow/stepRouter.ts
@@ -8,11 +8,10 @@
*
* Source of truth: STAGE-2-STEP-EXECUTION-ENGINE.md §4.3–§4.4
*/
-import Ajv, { type ValidateFunction } from 'ajv'
import { logger } from '../logger'
import { VisualInputBudget } from '../visualInput/policy'
+import { argumentValidator, checkToolArguments } from './argumentGate'
import { projectInternalToolResult } from './internalToolProjection'
-import { withoutUnsetNulls } from './schemaArguments'
import {
AllowedToolsConfig,
InternalToolDefinition,
@@ -98,10 +97,8 @@ export class StepMcpRouter {
private connections = new Map<string, McpClientConnection>()
private toolMap = new Map<string, { serverName: string; rawToolName: string }>()
private internalToolMap = new Map<string, InternalToolDefinition>()
- private internalToolValidators = new Map<string, ValidateFunction>()
private allTools: ToolDefinition[] = []
private readonly clientFactory: McpClientFactory
- private readonly ajv = new Ajv({ allErrors: true, strict: false, useDefaults: true })
private outputDir = '/output'
// Names callTool() may dispatch when the step declares a non-empty
// allowedTools.include. null = no allowlist in effect (every registered tool
@@ -118,9 +115,10 @@ export class StepMcpRouter {
* Register internal tools (clerum__*) that execute locally without MCP connection.
* Must be called before connect() so they appear in getFilteredTools().
*
- * The tool's `parameters` JSON Schema is compiled into an AJV validator that
- * runs before each dispatch. Bad LLM output (wrong type, missing required,
- * unknown enum value) is rejected before reaching `execute()`.
+ * The tool's `parameters` JSON Schema is compiled here into the validator
+ * that runs before each dispatch (argumentGate.ts, shared with chat). Bad LLM
+ * output (wrong type, missing required, unknown enum value) is rejected
+ * before reaching `execute()`.
*/
registerInternalTools(tools: InternalToolDefinition[], outputDir: string): void {
this.outputDir = outputDir
@@ -131,13 +129,9 @@ export class StepMcpRouter {
inputSchema: tool.parameters,
})
this.internalToolMap.set(tool.name, tool)
- try {
- this.internalToolValidators.set(tool.name, this.ajv.compile(tool.parameters))
- } catch (err) {
- // Schema failed to compile — dispatch falls through to runtime arg type-checking.
- // Surface the failure so schema regressions don't pass silently.
- logger.warn({ err, toolName: tool.name }, 'Internal tool schema compilation failed')
- }
+ // Compiled now so a schema that fails to compile is reported at
+ // registration; dispatch then falls through to the tool's own checks.
+ argumentValidator(tool)
// Also register in toolMap for consistent dispatch
this.toolMap.set(tool.name, {
serverName: 'clerum',
@@ -292,19 +286,15 @@ export class StepMcpRouter {
// Check internal tools first
const internalTool = this.internalToolMap.get(toolName)
if (internalTool) {
- // A null sent for an optional argument counts as unset, as the tool
- // itself reads it on the chat path, here before validation so it passes.
+ // The same check as on the chat path: unset nulls dropped, then the
+ // schema. Failures come back as recoverable tool-error results (not
+ // thrown) so the LLM can read the error and retry within the same step.
// The record keeps what the model sent.
- const input = withoutUnsetNulls(internalTool.parameters, args) as Record<string, unknown>
- // Validate args against the tool's JSON Schema before dispatch.
- // Failures come back as recoverable tool-error results (not thrown)
- // so the LLM can read the error and retry within the same step.
- const validator = this.internalToolValidators.get(toolName)
- if (validator && !validator(input)) {
- const errorText = this.ajv.errorsText(validator.errors, { separator: '; ' })
+ const checked = checkToolArguments(internalTool, args)
+ if (!checked.ok) {
const errorResult = {
success: false,
- error: `Invalid arguments: ${errorText}`,
+ error: checked.error,
}
const record: ToolCallRecord = {
serverName: 'clerum',
@@ -320,7 +310,7 @@ export class StepMcpRouter {
}
const start = Date.now()
const internalResult = projectInternalToolResult(
- await internalTool.execute(input, this.outputDir, {
+ await internalTool.execute(checked.input, this.outputDir, {
signal: options.signal,
timeoutMs: options.timeoutMs,
readBudget: this.readBudget,
@@ -375,7 +365,6 @@ export class StepMcpRouter {
this.connections.clear()
this.toolMap.clear()
this.internalToolMap.clear()
- this.internalToolValidators.clear()
this.allTools = []
}
}