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.tsnew file mode 100644index 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.tsindex 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.outputDirif (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.tsnew file mode 100644index 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.tsindex 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 dispatchthis.toolMap.set(tool.name, {serverName: 'clerum',@@ -292,19 +286,15 @@ export class StepMcpRouter {// Check internal tools firstconst 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 = []}}