Skip to content

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

TypeScript

fix(mcp-host): bound CLERUM_TOOL_PROGRESS_INTERVAL_MS

Alfredo Lopez8da3e5fcfae9
diff --git a/mcp-host/README.md b/mcp-host/README.md
index c419b641b..a19ee74fb 100644
--- a/mcp-host/README.md
+++ b/mcp-host/README.md
@@ -49,6 +49,7 @@ MCP Host is a Kubernetes-native service that reads Host CRD configuration and pr
| `CLERUM_WORKSPACE_PATH` | Base workspace path used by native tools and workspace-aware operations. | `CLERUM_WORKSPACE_PATH=/workspace` |
| `CLERUM_SHELL_TIMEOUT` | Maximum execution time in milliseconds for shell native-tool commands. A value whose sum with the 6000 ms shell cleanup window exceeds 2^31-1 ms (the Node.js timer limit), that is any value above 2147477647, is rejected and the Host stops at startup. | `CLERUM_SHELL_TIMEOUT=1500000` |
| `CLERUM_TOOL_TIMEOUT` | Maximum execution time in milliseconds for native tool wrapper calls. This is separate from the MCP SDK request timeout controlled by `CLERUM_MCP_TOOL_TIMEOUT_MS`. Like `CLERUM_SHELL_TIMEOUT`, a value above 2147477647 (value + 6000 ms > 2^31-1 ms) is rejected and the Host stops at startup. | `CLERUM_TOOL_TIMEOUT=1500000` |
+| `CLERUM_TOOL_PROGRESS_INTERVAL_MS` | Milliseconds between native-tool progress snapshots. Default 30000. Set 0 to disable periodic progress snapshots; any other value must be a whole decimal integer from 1000 to 2147483647 (inclusive). Any other explicit value, including an empty one, stops the Host at startup; values are never clamped or replaced by the default. | `CLERUM_TOOL_PROGRESS_INTERVAL_MS=30000` |
| `CLERUM_HTTP_ALLOWLIST` | Comma-separated allowlist of outbound hosts/URLs allowed for HTTP native tools. With an allowlist set, you can also skip per-call approval by adding `tools: { http_request: false }` under `Host.spec.approval` (see Host CRD). | `CLERUM_HTTP_ALLOWLIST=api.github.com,example.com` |
| `CLERUM_ENV_ALLOWLIST` | Comma-separated list of environment variables forwarded into native tool execution contexts. | `CLERUM_ENV_ALLOWLIST=PATH,HOME,USER,SHELL,LANG,TERM` |
| `CLERUM_MEMORY_MAX_SIZE` | Maximum bytes reserved for in-memory native tool buffers/state. | `CLERUM_MEMORY_MAX_SIZE=1048576` |
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 66063ae3d..6762357d1 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.515",
+ "version": "0.1.516",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.515",
+ "version": "0.1.516",
"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 e78313f38..a55b5f02b 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.515",
+ "version": "0.1.516",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/config.toolProgressInterval.test.ts b/mcp-host/src/config.toolProgressInterval.test.ts
new file mode 100644
index 000000000..c8b9ad995
--- /dev/null
+++ b/mcp-host/src/config.toolProgressInterval.test.ts
@@ -0,0 +1,146 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { Tool } from './core/interfaces'
+import { executeSingleTool } from './core/orchestration/toolUseLoopSingleTool'
+import type { ToolOutput } from './core/types'
+
+const KEY = 'CLERUM_TOOL_PROGRESS_INTERVAL_MS'
+const MESSAGE =
+ 'CLERUM_TOOL_PROGRESS_INTERVAL_MS must be 0 (disables tool progress streaming) or an integer from 1000 to 2147483647 (inclusive)'
+
+afterEach(() => {
+ vi.useRealTimers()
+ vi.unstubAllEnvs()
+ vi.resetModules()
+})
+
+async function intervalFor(value: string | undefined): Promise<number> {
+ vi.resetModules()
+ vi.stubEnv(KEY, value)
+ const { config } = await import('./config')
+ return config.nativeTool.toolProgressInterval
+}
+
+async function startupErrorFor(value: string): Promise<unknown> {
+ vi.resetModules()
+ vi.stubEnv(KEY, value)
+ return import('./config').then(
+ () => undefined,
+ (error: unknown) => error
+ )
+}
+
+/**
+ * Runs one progress-capable tool call through executeSingleTool, the consumer
+ * of the interval, for 1500 ms of fake time and counts the snapshots.
+ */
+async function snapshotsWithInterval(toolProgressInterval: number) {
+ vi.useFakeTimers()
+ const reporter = {
+ reportToolStart: vi.fn(),
+ reportToolComplete: vi.fn(),
+ reportToolProgress: vi.fn(),
+ reportThinking: vi.fn(),
+ reportLlmInProgress: vi.fn(),
+ }
+ let finish!: (output: ToolOutput) => void
+ const tool: Tool = {
+ name: () => 'shell_exec',
+ description: () => 'progress-capable tool',
+ parametersSchema: () => ({ type: 'object', properties: {} }),
+ execute: (_params, context) =>
+ new Promise<ToolOutput>(resolve => {
+ finish = resolve
+ context?.onOutput('line one\n')
+ }),
+ requiresSanitization: () => false,
+ requiresApproval: () => false,
+ supportsProgressOutput: () => true,
+ }
+ const config = {
+ toolRegistry: { get: () => tool },
+ toolOutputProcessor: {
+ beforeExecution: () => ({ is_valid: true, errors: [] }),
+ afterExecution: (_name: string, output: ToolOutput) => output.content,
+ },
+ safety: {
+ sanitizeOutput: (_name: string, output: string) => ({
+ content: output,
+ was_modified: false,
+ warnings: [],
+ }),
+ },
+ events: { emit: () => {} },
+ toolTimeout: 60_000,
+ toolProgressInterval,
+ progressReporter: reporter,
+ } as unknown as Parameters<typeof executeSingleTool>[1]
+ const pending = executeSingleTool(
+ { id: 'call-1', name: 'shell_exec', arguments: { command: 'x' } },
+ config
+ )
+ await vi.advanceTimersByTimeAsync(1_500)
+ finish({ content: 'done', is_error: false, duration_ms: 1 })
+ const result = await pending
+ vi.useRealTimers()
+ return {
+ snapshots: reporter.reportToolProgress.mock.calls.length,
+ result,
+ }
+}
+
+describe('CLERUM_TOOL_PROGRESS_INTERVAL_MS (#1028 P2)', () => {
+ it('P2-a: unset keeps 30000, 0 disables periodic snapshots through executeSingleTool, and 1000 produces one', async () => {
+ expect(await intervalFor(undefined)).toBe(30_000)
+
+ const enabled = await intervalFor('1000')
+ expect(enabled).toBe(1_000)
+ const enabledRun = await snapshotsWithInterval(enabled)
+ // Witness: the same consumer publishes a snapshot at the 1000 ms interval.
+ expect(enabledRun.snapshots).toBe(1)
+ expect(enabledRun.result).toMatchObject({ is_error: false, content: 'done' })
+
+ const disabled = await intervalFor('0')
+ expect(disabled).toBe(0)
+ const disabledRun = await snapshotsWithInterval(disabled)
+ expect(disabledRun.snapshots).toBe(0)
+ // The call itself still completes with the tool's output.
+ expect(disabledRun.result).toMatchObject({ is_error: false, content: 'done' })
+ })
+
+ it('P2-b: malformed and sub-second values stop startup with the exact message and do not echo the value', async () => {
+ // Witness: the same import succeeds with a valid value first.
+ expect(await intervalFor('1000')).toBe(1_000)
+
+ const rejected = [
+ '',
+ ' 1000',
+ '1000 ',
+ '+1000',
+ '-1',
+ '1.5',
+ '1e4',
+ '10s',
+ 'abc',
+ '1',
+ '999',
+ '0x3e8',
+ 'Infinity',
+ ]
+ for (const value of rejected) {
+ const error = await startupErrorFor(value)
+ expect(error, `value ${JSON.stringify(value)}`).toBeInstanceOf(Error)
+ // Exact equality: the message is fixed and carries no part of the value.
+ expect((error as Error).message, `value ${JSON.stringify(value)}`).toBe(MESSAGE)
+ }
+ }, 30_000)
+
+ it('P2-c: 1000 and 2147483647 are accepted inclusively, 0001000 reads as 1000, and 2147483648 is rejected', async () => {
+ expect(await intervalFor('1000')).toBe(1_000)
+ expect(await intervalFor('2147483647')).toBe(2_147_483_647)
+ expect(await intervalFor('0001000')).toBe(1_000)
+
+ const error = await startupErrorFor('2147483648')
+ expect(error).toBeInstanceOf(Error)
+ expect((error as Error).message).toBe(MESSAGE)
+ })
+})
diff --git a/mcp-host/src/config.ts b/mcp-host/src/config.ts
index 8c71ea212..0cffedd47 100644
--- a/mcp-host/src/config.ts
+++ b/mcp-host/src/config.ts
@@ -372,6 +372,33 @@ function getExecutionLimit(
return value
}
+/** Progress snapshots are never scheduled more than once per second. */
+const MIN_TOOL_PROGRESS_INTERVAL_MS = 1000
+
+/**
+ * Milliseconds between native-tool progress snapshots. Unset keeps 30000; 0
+ * disables periodic snapshots; any other value must be a whole decimal integer
+ * from 1000 to the Node.js timer range. Anything else stops the Host at
+ * startup: a larger value would fire every millisecond and NaN would silently
+ * disable progress. The raw value is never echoed.
+ */
+function getToolProgressIntervalMs(): number {
+ const key = 'CLERUM_TOOL_PROGRESS_INTERVAL_MS'
+ const raw = getEnv(key)
+ if (raw === undefined) return 30000
+ const value = Number(raw)
+ if (
+ !/^\d+$/.test(raw) ||
+ !Number.isSafeInteger(value) ||
+ (value !== 0 && (value < MIN_TOOL_PROGRESS_INTERVAL_MS || value > MAX_TIMER_DELAY_MS))
+ ) {
+ throw new Error(
+ `${key} must be 0 (disables tool progress streaming) or an integer from ${MIN_TOOL_PROGRESS_INTERVAL_MS} to ${MAX_TIMER_DELAY_MS} (inclusive)`
+ )
+ }
+ return value
+}
+
function getEnvBool(key: string, defaultValue: boolean): boolean {
const value = process.env[key]
if (!value) return defaultValue
@@ -1067,7 +1094,7 @@ export const config: Config = {
workspacePath: process.env.CLERUM_WORKSPACE_PATH || process.cwd(),
shellTimeout: getExecutionLimit('CLERUM_SHELL_TIMEOUT', 1500000, false, MAX_TOOL_TIMEOUT_MS),
toolTimeout: getExecutionLimit('CLERUM_TOOL_TIMEOUT', 1500000, false, MAX_TOOL_TIMEOUT_MS),
- toolProgressInterval: parseInt(getEnv('CLERUM_TOOL_PROGRESS_INTERVAL_MS', '30000')!, 10),
+ toolProgressInterval: getToolProgressIntervalMs(),
httpAllowlist: (process.env.CLERUM_HTTP_ALLOWLIST || '')
.split(',')
.map(s => s.trim())