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 tool timeout to the executable timer range

Alfredo Lopezaaf9a06a62fc
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index affae0926..b8d39b9eb 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.502",
+ "version": "0.1.503",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.502",
+ "version": "0.1.503",
"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 41ab8c29c..7af022fab 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.502",
+ "version": "0.1.503",
"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.executionLimits.test.ts b/mcp-host/src/config.executionLimits.test.ts
index 559386ba1..1e6001f4c 100644
--- a/mcp-host/src/config.executionLimits.test.ts
+++ b/mcp-host/src/config.executionLimits.test.ts
@@ -1,4 +1,9 @@
import { afterEach, describe, expect, it, vi } from 'vitest'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { executeWithTimeout } from './core/orchestration/toolExecutionTimeout'
+import { ShellTool } from './core/tools/shell'
import { resolveMcpRequestTimeoutMs } from './mcp/requestOptions'
const names = [
@@ -58,3 +63,54 @@ describe('execution limit validation', () => {
expect(resolveMcpRequestTimeoutMs()).toBe(1500000)
})
})
+
+describe('tool timeouts bounded to the executable timer range (#1021)', () => {
+ const maxTimerDelayMs = 2_147_483_647
+ const shellCleanupMs = new ShellTool(undefined, 1, ['PATH']).timeoutCleanupMs()
+ const largestTimeout = maxTimerDelayMs - shellCleanupMs
+
+ it('reserves the 6s cleanup the shell declares', () => {
+ expect(shellCleanupMs).toBe(6_000)
+ expect(largestTimeout).toBe(2_147_477_647)
+ })
+
+ it.each(['CLERUM_TOOL_TIMEOUT', 'CLERUM_SHELL_TIMEOUT'])(
+ 'U11: accepts %s at 2^31-1 minus the shell cleanup and rejects one more',
+ async name => {
+ vi.resetModules()
+ vi.stubEnv(name, String(largestTimeout))
+ const { config } = await import('./config')
+ const field = name === 'CLERUM_TOOL_TIMEOUT' ? 'toolTimeout' : 'shellTimeout'
+ expect(config.nativeTool[field]).toBe(largestTimeout)
+
+ vi.resetModules()
+ vi.stubEnv(name, String(largestTimeout + 1))
+ await expect(import('./config')).rejects.toThrow(`${name} must be a valid bounded integer`)
+ }
+ )
+
+ it('U11: the accepted maximum runs a shell call and one more is refused by the timer guard', async () => {
+ const workspace = await mkdtemp(join(tmpdir(), 'clerum-timeout-bound-'))
+ try {
+ const shell = new ShellTool(workspace, largestTimeout, ['PATH'])
+ const output = await executeWithTimeout(
+ shell,
+ { command: 'printf u11-ok' },
+ { onOutput: () => undefined },
+ largestTimeout
+ )
+ expect(output.is_error).toBe(false)
+ expect(output.content).toContain('u11-ok')
+ await expect(
+ executeWithTimeout(
+ shell,
+ { command: 'printf u11-never' },
+ { onOutput: () => undefined },
+ largestTimeout + 1
+ )
+ ).rejects.toThrow('Invalid tool execution or cleanup timeout')
+ } finally {
+ await rm(workspace, { recursive: true, force: true })
+ }
+ })
+})
diff --git a/mcp-host/src/config.ts b/mcp-host/src/config.ts
index 66de689af..a58c799ed 100644
--- a/mcp-host/src/config.ts
+++ b/mcp-host/src/config.ts
@@ -10,6 +10,7 @@ import {
parseCodexToolDiscoveryBytes,
parseCodexToolPresentation,
} from './core/orchestration/toolPresentationPolicy'
+import { SHELL_TIMEOUT_CLEANUP_MS } from './core/tools/shellTimeouts'
import { ALL_PROVIDERS, type LlmProvider, descriptorFor, isLlmProvider } from './llm/registryCore'
import type { McpCatalogBootstrapConfig } from './mcp/grantProbe'
import { HostSpec, McpServerInfo, MemoryConfig, ModelConfig, PersonalizationConfig } from './types'
@@ -328,7 +329,22 @@ function getEnv(key: string, defaultValue?: string): string | undefined {
return process.env[key] ?? defaultValue
}
-function getExecutionLimit(key: string, defaultValue: number, allowZero = false): number {
+/** Largest delay, in ms, that a Node.js timer accepts. */
+const MAX_TIMER_DELAY_MS = 2_147_483_647
+
+/**
+ * Upper bound for a tool timeout: executeWithTimeout arms the shell's cleanup
+ * timer on top of the execution deadline and rejects a sum above the timer
+ * range, so a larger value would fail every shell call at runtime (#1021).
+ */
+const MAX_TOOL_TIMEOUT_MS = MAX_TIMER_DELAY_MS - SHELL_TIMEOUT_CLEANUP_MS
+
+function getExecutionLimit(
+ key: string,
+ defaultValue: number,
+ allowZero = false,
+ maximum = MAX_TIMER_DELAY_MS
+): number {
const raw = getEnv(key)
if (raw === undefined) return defaultValue
const value = Number(raw)
@@ -336,7 +352,7 @@ function getExecutionLimit(key: string, defaultValue: number, allowZero = false)
!/^\d+$/.test(raw) ||
!Number.isSafeInteger(value) ||
value < (allowZero ? 0 : 1) ||
- value > 2_147_483_647
+ value > maximum
) {
throw new Error(`${key} must be a valid bounded integer`)
}
@@ -1013,8 +1029,8 @@ export const config: Config = {
// Native tool configuration
nativeTool: {
workspacePath: process.env.CLERUM_WORKSPACE_PATH || process.cwd(),
- shellTimeout: getExecutionLimit('CLERUM_SHELL_TIMEOUT', 1500000),
- toolTimeout: getExecutionLimit('CLERUM_TOOL_TIMEOUT', 1500000),
+ 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),
httpAllowlist: (process.env.CLERUM_HTTP_ALLOWLIST || '')
.split(',')
diff --git a/mcp-host/src/core/tools/shell.ts b/mcp-host/src/core/tools/shell.ts
index c4a45e69a..e81be4832 100644
--- a/mcp-host/src/core/tools/shell.ts
+++ b/mcp-host/src/core/tools/shell.ts
@@ -6,6 +6,7 @@ import { verifyManagedCallerRootPath } from '../../workspace/callerRootBinding'
import { ToolError, ToolErrorCode } from '../errors'
import { ExecutionContext, Tool } from '../interfaces'
import { ToolOutput } from '../types'
+import { SHELL_SIGKILL_GRACE_MS, SHELL_TIMEOUT_CLEANUP_MS } from './shellTimeouts'
// D3 (stateless-agents) §1.2 — lexical defense-in-depth: reject commands that
// reference the session state database (state.db + WAL laterals) or the
@@ -68,7 +69,7 @@ export class ShellTool implements Tool {
/** Leaves room for status text, XML wrapping, and message serialization. */
private static readonly MAX_RESULT_BYTES = ShellTool.MAX_TOTAL_BYTES - 2048
private static readonly MAX_PROGRESS_BYTES = 64 * 1024
- static readonly SIGKILL_GRACE_MS = 5000
+ static readonly SIGKILL_GRACE_MS = SHELL_SIGKILL_GRACE_MS
/**
* `dynamicEnvProvider` returns operator-managed env vars from the
@@ -137,8 +138,7 @@ export class ShellTool implements Tool {
}
timeoutCleanupMs(): number {
- // Termination has an existing 5s SIGKILL grace; allow 1s for close/output delivery.
- return ShellTool.SIGKILL_GRACE_MS + 1000
+ return SHELL_TIMEOUT_CLEANUP_MS
}
joinsAbortSettlement(): boolean {
diff --git a/mcp-host/src/core/tools/shellTimeouts.ts b/mcp-host/src/core/tools/shellTimeouts.ts
new file mode 100644
index 000000000..128751103
--- /dev/null
+++ b/mcp-host/src/core/tools/shellTimeouts.ts
@@ -0,0 +1,10 @@
+/** Grace period between SIGTERM and SIGKILL for a timed-out shell process group. */
+export const SHELL_SIGKILL_GRACE_MS = 5000
+
+/**
+ * Bounded termination and result collection after a shell deadline: the
+ * SIGKILL grace plus 1s for close/output delivery. executeWithTimeout adds it to
+ * the execution deadline, so a configured timeout must leave room for it below
+ * the largest delay a Node.js timer accepts (#1021).
+ */
+export const SHELL_TIMEOUT_CLEANUP_MS = SHELL_SIGKILL_GRACE_MS + 1000