Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import { type ChildProcess, spawn } from 'child_process'
import { setTimeout as sleep } from 'node:timers/promises'
import { recordGfsShellOutputLimit } from '../../internalTools/gfsDownloadMetrics'
import { ALL_PROVIDERS, LlmProvider, PROVIDERS } from '../../llm/registryCore'
import { logger } from '../../logger'
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_STDIO_DRAIN_MS,
SHELL_TIMEOUT_CLEANUP_MS,
} from './shellTimeouts'
// Reject commands that name a conversation-store file or the reserved
// `.clerum-state/` runtime directory before spawning. Every name starting
// with `state.db` is store data: the database, its journals and the
// `state.db*.pre-<ts>.bak` copies an older layout left at the workspace root.
// The left boundary keeps "mystate.db" usable. Case-sensitive, matching the
// on-disk names.
// This is a lexical name check only, not a security boundary: the shell runs
// with the database's UID, so a glob, a variable or a symlink reaches the same
// files. The workspace API checks resolved paths; the shell does not.
const STATE_DB_COMMAND_PATTERN = /(^|[^A-Za-z0-9_.-])state\.db|\.clerum-state(\/|[^A-Za-z0-9_.-]|$)/
// Node/libuv error codes (E2BIG, ENOMEM, ERR_INVALID_ARG_VALUE) are fixed
// identifiers; anything else is not echoed to the model.
const SPAWN_ERROR_CODE_PATTERN = /^[A-Z0-9_]+$/
/** Returns a well-formed Node/libuv error code, never any part of the message. */
function wellFormedErrorCode(error: unknown): string | undefined {
const rawCode = (error as NodeJS.ErrnoException | undefined)?.code
return typeof rawCode === 'string' && SPAWN_ERROR_CODE_PATTERN.test(rawCode) ? rawCode : undefined
}
function truncateUtf8Bytes(value: string, maximumBytes: number): string {
if (maximumBytes <= 0) return ''
const bytes = Buffer.from(value, 'utf8')
if (bytes.length <= maximumBytes) return value
return bytes
.subarray(0, maximumBytes)
.toString('utf8')
.replace(/\uFFFD$/u, '')
}
/**
* Only ESRCH confirms that the group is gone. EPERM means it exists under
* another owner; any other failure leaves absence unconfirmed, so the group is
* treated as present and the code is logged.
*/
function processGroupExists(processGroupId: number): boolean {
try {
process.kill(-processGroupId, 0)
return true
} catch (error) {
const code = (error as NodeJS.ErrnoException).code
if (code === 'ESRCH') return false
if (code !== 'EPERM') {
logger.warn(
{ component: 'ShellTool', errorCode: wellFormedErrorCode(error) ?? 'UNKNOWN' },
'Shell process-group probe failed; group absence is not confirmed'
)
}
return true
}
}
/**
* Sends SIGKILL to the group and polls for its absence. Polling stops after
* about one second, or at `deadlineAt` (a `performance.now()` value) when the
* call is already inside its declared termination budget.
*/
async function ensureProcessGroupTerminated(
processGroupId: number,
deadlineAt?: number
): Promise<boolean> {
try {
process.kill(-processGroupId, 'SIGKILL')
} catch {
/* The group can exit between leader close and this signal. */
}
for (let attempt = 0; attempt < 100; attempt += 1) {
if (!processGroupExists(processGroupId)) return true
if (deadlineAt !== undefined) {
const remaining = deadlineAt - performance.now()
if (remaining <= 0) break
await sleep(Math.min(10, remaining))
} else {
await sleep(10)
}
}
return !processGroupExists(processGroupId)
}
function isValidProcessId(pid: number | undefined): pid is number {
return typeof pid === 'number' && Number.isSafeInteger(pid) && pid > 0
}
/**
* ShellTool — runs an arbitrary shell command in the agent's workspace.
*
* HIGH RISK — gated behind requiresApproval(). The user sees and approves
* every command before execution; that is the trust boundary.
*
* Uses child_process.spawn (not exec) so we can:
* 1. Stream output to the progress watcher via ExecutionContext.onOutput
* 2. Return partial stdout/stderr when the command is killed by timeout,
* giving the LLM something to reason about instead of a bare error.
*
* Each execute() call creates its own local state (stdout/stderr buffers,
* timers) — no shared state across concurrent invocations.
*/
export class ShellTool implements Tool {
private static readonly MAX_TOTAL_BYTES = 1024 * 1024 // 1 MB — preserved from pre-spawn behavior
/** 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 = SHELL_SIGKILL_GRACE_MS
/**
* `dynamicEnvProvider` returns operator-managed env vars from the
* ConfigStore (per-Host CM/Secret + the LLM key). Merged into the child's
* env at spawn time so the LLM can reference them via `$VAR` and let the
* subprocess shell expand them — mcp-host never substitutes in JS.
*/
constructor(
private readonly workspacePath: string | undefined,
private readonly timeout: number,
private readonly envAllowlist: string[],
private readonly dynamicEnvProvider: () => Record<string, string> = () => ({}),
// §13 (stateless agents) — the ACTIVE LLM provider. Steers credential-slot
// stripping: only this provider's credential env var survives into the
// child env; every other provider slot is deleted. Undefined (tool-name
// listing registry, legacy tests) strips ALL slots — the secure default.
private readonly activeLlmProvider?: LlmProvider,
/**
* Re-verify that the caller workspace root is still canonical before every
* command. Set for Host-managed per-user roots; this is per-user directory
* scoping and never touches the GFS download store.
*/
private readonly verifyCallerRoot: boolean = false
) {}
name() {
return 'shell_exec'
}
description() {
return (
'Execute a shell command in the workspace directory. ' +
'Supports full shell syntax (pipes, redirects, &&, etc.). ' +
'Commands run with a timeout and restricted environment. ' +
`Node.js executable: ${JSON.stringify(process.execPath)}. ` +
`Resolve installed Host libraries with require('node:module').createRequire(${JSON.stringify(require.resolve('exceljs'))}); load fast-csv through that resolver and use parseStream for streaming CSV parsing (exceljs.csv is not available). ` +
'Verify any other executable or library before using it. ' +
'This tool requires approval before execution.'
)
}
parametersSchema() {
return {
type: 'object',
properties: {
command: {
type: 'string',
description:
"The shell command to execute (e.g., 'ls -la', 'echo hello | wc -c', 'git status')",
},
},
required: ['command'],
}
}
requiresSanitization(): boolean {
return true
}
requiresApproval(): boolean {
return true
} // HIGH RISK — approval gate is the security boundary
supportsProgressOutput(): boolean {
return true
}
timeoutCleanupMs(): number {
return SHELL_TIMEOUT_CLEANUP_MS
}
joinsAbortSettlement(): boolean {
return true
}
async execute(params: Record<string, unknown>, context?: ExecutionContext): Promise<ToolOutput> {
context?.signal?.throwIfAborted()
const timeout = Math.min(this.timeout, context?.timeoutMs ?? this.timeout)
const startTime = Date.now()
const command = params.command as string
if (this.verifyCallerRoot && this.workspacePath) {
if (verifyManagedCallerRootPath(this.workspacePath) === undefined) {
return this.managedRootUnavailable(startTime)
}
}
if (!this.workspacePath) {
return {
content:
'Managed shell unavailable: no verified caller workspace is available for this Host runtime.',
duration_ms: Date.now() - startTime,
is_error: true,
}
}
if (STATE_DB_COMMAND_PATTERN.test(command)) {
return {
content:
'Command rejected: it references the session state database ' +
'(state.db* / .clerum-state), which is ' +
'platform-managed state the agent cannot access.',
duration_ms: Date.now() - startTime,
is_error: true,
}
}
const safeEnv: Record<string, string> = {
HOME: this.workspacePath, // Sandbox HOME to prevent leaking host config (~/.gitconfig, etc.)
}
for (const key of this.envAllowlist) {
if (process.env[key]) {
safeEnv[key] = process.env[key]!
}
}
// Layer ConfigStore values on top so operator-managed env (per-Host
// CM/Secret + the LLM key) is visible to the subprocess shell. The
// shell — not mcp-host — expands `$VAR` at runtime; secret values
// never enter mcp-host's JS state outside of this single env object.
const dynamicEnv = this.dynamicEnvProvider()
for (const [k, v] of Object.entries(dynamicEnv)) {
if (typeof v === 'string') safeEnv[k] = v
}
// Set HOME after operator/dynamic environment merging. A supplied HOME must
// never relocate the approved shell outside the caller's workspace root.
safeEnv.HOME = this.workspacePath
// §13 (stateless agents) — credential-slot stripping. The child env
// carries ONLY the ACTIVE provider's credential slots; every OTHER
// provider's credential env vars are explicitly deleted, even when present
// in process.env (via the allowlist) or in the ConfigStore layer above.
// The slot set is DERIVED from the provider registry (registryCore
// PROVIDERS), so a future provider is stripped automatically. Multi-slot
// providers (R4: Bedrock's key pair, Vertex's SA JSON) keep ALL of the
// active provider's slots; primarySlot() is deliberately NOT used here
// (the exclusion boundary must span the full slot set — spec §3-R4.3).
const activeProvider = this.activeLlmProvider
for (const provider of ALL_PROVIDERS) {
if (provider === activeProvider) continue
for (const slot of PROVIDERS[provider].credentialSlots) {
delete safeEnv[slot.envName]
}
}
// A NUL byte in an env value (e.g. a ConfigStore secret, which BasicSafety
// never sees, #1020) makes spawn() throw ERR_INVALID_ARG_VALUE with up to
// 128 characters of the raw value in its message. Reject it here and name
// only the key, so no part of the value reaches the model or the logs.
for (const [key, value] of Object.entries(safeEnv)) {
if (value.includes('\0')) {
logger.error(
{ component: 'ShellTool', errorCode: 'ENV_VALUE_CONTAINS_NUL' },
'Shell command failed to start'
)
return {
content: `Command failed to start: environment variable ${key} contains a NUL character`,
duration_ms: Date.now() - startTime,
is_error: true,
}
}
}
return new Promise<ToolOutput>(resolve => {
// detached: true makes the child a process group leader so we can kill
// the whole group (shell + grandchildren like `sleep`) with -pid signal.
let child: ChildProcess
try {
child = spawn('/bin/sh', ['-c', command], {
cwd: this.workspacePath,
env: safeEnv,
stdio: ['ignore', 'pipe', 'pipe'],
detached: true,
})
} catch (error) {
// spawn() throws synchronously for invalid arguments and for most libuv
// errors (E2BIG for an oversized command, ENOMEM under memory pressure).
// No process exists, so this is a start failure reported as an error
// result. Node error messages can embed argument and env values, so
// only a well-formed error code is reported, never the message.
const errorCode = wellFormedErrorCode(error)
logger.error(
{ component: 'ShellTool', errorCode: errorCode ?? 'UNKNOWN' },
'Shell command failed to start'
)
resolve({
content:
errorCode === undefined
? 'Command failed to start'
: `Command failed to start: ${errorCode}`,
duration_ms: Date.now() - startTime,
is_error: true,
})
return
}
const stdoutBuf: Buffer[] = []
const stderrBuf: Buffer[] = []
let totalBytes = 0
let progressBytes = 0
// The first cause wins; later events never overwrite it.
let killed: 'timeout' | 'maxbuffer' | 'cancelled' | null = null
let resolved = false
// Claimed synchronously by the first finalizer (close, drain check,
// cleanup deadline, start failure). Every later path returns.
let finalizing = false
let terminationStartedAt: number | undefined
let killTimer: ReturnType<typeof setTimeout> | undefined
let deadlineTimer: ReturnType<typeof setTimeout> | undefined
let drainTimer: ReturnType<typeof setInterval> | undefined
const resolveOnce = (out: ToolOutput) => {
if (resolved) return
resolved = true
resolve(out)
}
const clearFinalizationTimers = () => {
clearInterval(drainTimer)
drainTimer = undefined
clearTimeout(deadlineTimer)
deadlineTimer = undefined
}
const claimFinalization = (): boolean => {
if (finalizing) return false
finalizing = true
clearFinalizationTimers()
return true
}
const forceKill = () => {
// Kill the entire process group so grandchildren (e.g., `sleep` inside a
// semi-colon chain) are also terminated and the stdout/stderr pipes close.
// Guard against undefined/zero pid: process.kill(-0, ...) would signal the
// entire process group mcp-host belongs to. Fall back to child.kill() if
// pid is not a valid positive integer.
const pid = child.pid
const canGroupKill = typeof pid === 'number' && pid > 0
if (canGroupKill) {
try {
process.kill(-pid, 'SIGTERM')
} catch {
child.kill('SIGTERM')
}
} else {
child.kill('SIGTERM')
}
terminationStartedAt = performance.now()
// Termination owns settlement from here; the natural-exit drain poll stops.
clearInterval(drainTimer)
drainTimer = undefined
killTimer = setTimeout(() => {
if (canGroupKill) {
try {
process.kill(-(pid as number), 'SIGKILL')
} catch {
if (!child.killed) child.kill('SIGKILL')
}
} else if (!child.killed) {
child.kill('SIGKILL')
}
}, ShellTool.SIGKILL_GRACE_MS)
killTimer.unref?.()
// A process outside the group can hold stdout/stderr open after the
// group is gone, so `close` may never arrive. The deadline bounds the
// call to the declared cleanup budget.
deadlineTimer = setTimeout(() => finalizeAtCleanupDeadline(), SHELL_TIMEOUT_CLEANUP_MS)
}
const onChunk = (chunk: Buffer, which: 'stdout' | 'stderr') => {
if (finalizing) return
// Bound both destinations before accepting the chunk. Bytes beyond the
// admission bound are counted only for the truthful limit decision and
// never enter retained output.
if (totalBytes >= ShellTool.MAX_TOTAL_BYTES) {
if (!killed) {
killed = 'maxbuffer'
recordGfsShellOutputLimit('output_limit_exceeded')
forceKill()
}
return
}
const retained = Math.min(chunk.length, ShellTool.MAX_TOTAL_BYTES - totalBytes)
if (retained > 0) stdoutOrStderr(which).push(chunk.subarray(0, retained))
totalBytes += chunk.length
// Progress is a live preview, not a second output channel. Stop it at
// its own fixed bound even while the final result is allowed to reach
// its larger admission bound.
const progressRemaining = ShellTool.MAX_PROGRESS_BYTES - progressBytes
if (progressRemaining > 0) {
const preview = chunk.subarray(0, progressRemaining)
progressBytes += preview.length
context?.onOutput(preview.toString('utf8'))
}
if (totalBytes > ShellTool.MAX_TOTAL_BYTES && !killed) {
killed = 'maxbuffer'
recordGfsShellOutputLimit('output_limit_exceeded')
forceKill()
}
}
function stdoutOrStderr(which: 'stdout' | 'stderr'): Buffer[] {
return which === 'stdout' ? stdoutBuf : stderrBuf
}
const onStdout = (chunk: Buffer) => onChunk(chunk, 'stdout')
const onStderr = (chunk: Buffer) => onChunk(chunk, 'stderr')
child.stdout?.on('data', onStdout)
child.stderr?.on('data', onStderr)
// Destroying the pipes bounds settlement; it does not contain or signal
// the process holding them, which may get EPIPE on later writes.
const stopOutputCapture = () => {
child.stdout?.off('data', onStdout)
child.stderr?.off('data', onStderr)
child.stdout?.destroy()
child.stderr?.destroy()
}
const timer = setTimeout(() => {
if (!killed && !finalizing) {
killed = 'timeout'
forceKill()
}
}, timeout)
const onAbort = () => {
if (!killed && !resolved && !finalizing) {
killed =
context?.signal?.reason instanceof ToolError &&
context.signal.reason.code === ToolErrorCode.Timeout
? 'timeout'
: 'cancelled'
forceKill()
}
}
const cleanup = () => {
clearTimeout(timer)
clearTimeout(killTimer)
clearFinalizationTimers()
context?.signal?.removeEventListener('abort', onAbort)
}
/** Builds and publishes the one result of this call. */
const publish = (
exitCode: number | null,
groupTerminated: boolean,
outputCaptureStopped: boolean,
cause: typeof killed
) => {
cleanup()
const stdout = Buffer.concat(stdoutBuf).toString('utf8')
const stderr = Buffer.concat(stderrBuf).toString('utf8')
const body =
[stdout ? `stdout:\n${stdout}` : '', stderr ? `stderr:\n${stderr}` : '']
.filter(Boolean)
.join('\n\n') || '(no output)'
// The completion summary keeps only the first 200 characters, so the
// forced-closure notice goes first.
const notice = outputCaptureStopped
? `[stdio_held_by_detached_process: ${cause ?? 'exited'}; output capture stopped; redirect background output to a file or /dev/null]\n\n`
: ''
const failure =
cause === null && exitCode !== 0 && exitCode !== null
? `Command failed (exit code ${exitCode}):\n`
: ''
let footers = ''
if (cause === 'timeout') {
footers += `\n\n[Command killed after ${timeout}ms timeout — partial output above]`
} else if (cause === 'cancelled') {
footers += '\n\n[Command cancelled — partial output above]'
} else if (cause === 'maxbuffer') {
footers += `\n\n[output_limit_exceeded: command killed after more than ${ShellTool.MAX_TOTAL_BYTES} output bytes — bounded partial output above]`
}
if (!groupTerminated) footers += '\n\n[process_group_termination_failed]'
// Every diagnostic is reserved before the body is truncated, so none
// erases another; a negative budget would keep almost the whole body.
const bodyBudget = Math.max(
0,
ShellTool.MAX_RESULT_BYTES - Buffer.byteLength(`${notice}${failure}${footers}`, 'utf8')
)
const durationMs = Date.now() - startTime
if (outputCaptureStopped) {
logger.warn(
{
component: 'ShellTool',
event: 'shell_stdio_held_by_detached_process',
reason: cause ?? 'exited',
exitCode,
leaderExited: child.exitCode !== null || child.signalCode !== null,
processGroupTerminated: groupTerminated,
durationMs,
},
"A process outside the command's process group kept stdout/stderr open; shell output capture stopped"
)
}
resolveOnce({
content: `${notice}${failure}${truncateUtf8Bytes(body, bodyBudget)}${footers}`,
duration_ms: durationMs,
is_error: outputCaptureStopped || cause !== null || failure !== '' || !groupTerminated,
})
}
// Termination path: `close` did not arrive within the cleanup budget.
const finalizeAtCleanupDeadline = () => {
if (!claimFinalization()) return
const pid = child.pid
if (isValidProcessId(pid)) {
try {
process.kill(-pid, 'SIGKILL')
} catch {
/* The group can already be gone; the probe below decides. */
}
} else if (!child.killed) {
child.kill('SIGKILL')
}
stopOutputCapture()
// One probe only: the budget is spent.
const groupTerminated = isValidProcessId(pid) ? !processGroupExists(pid) : true
publish(child.exitCode, groupTerminated, true, killed)
}
// Natural-exit path: the leader exited without a cause. Exit alone does
// not publish, because an in-group background job can still write; only
// the absence of the whole group does.
child.once('exit', () => {
const processGroupId = child.pid
if (killed || finalizing || !isValidProcessId(processGroupId)) return
let absentProbes = 0
drainTimer = setInterval(() => {
if (finalizing) return
if (processGroupExists(processGroupId)) {
absentProbes = 0
return
}
// The last in-group writer can exit before its pipe EOF reaches this
// process; under load that EOF can miss the poll phase below. Only a
// second consecutive absent probe without `close` means a process
// outside the group holds stdio.
absentProbes += 1
if (absentProbes < 2) return
// A pipe EOF pending in this poll phase delivers `close` first.
setImmediate(() => {
if (!claimFinalization()) return
stopOutputCapture()
publish(child.exitCode, true, true, killed)
})
}, SHELL_STDIO_DRAIN_MS)
})
const handleClose = async (exitCode: number | null): Promise<void> => {
if (!claimFinalization()) return
const cause = killed
// Leader/stdio close does not prove descendants exited. Always complete
// group termination before resolving, inside the cleanup budget when a
// cause already started it.
const processGroupId = child.pid
const deadlineAt =
cause !== null && terminationStartedAt !== undefined
? terminationStartedAt + SHELL_TIMEOUT_CLEANUP_MS
: undefined
const groupTerminated = isValidProcessId(processGroupId)
? await ensureProcessGroupTerminated(processGroupId, deadlineAt)
: true
publish(exitCode, groupTerminated, false, cause)
}
child.on('close', exitCode => {
void handleClose(exitCode)
})
child.on('error', error => {
// Node error messages can embed argument and env values, so only a
// well-formed error code is reported, never the message.
const errorCode = wellFormedErrorCode(error)
const loggedCode = errorCode ?? 'UNKNOWN'
if (isValidProcessId(child.pid)) {
// A started process reports `error` only when signalling it failed.
// Termination stays with the existing timers and cause.
logger.error(
{ component: 'ShellTool', errorCode: loggedCode },
'Shell process reported an error'
)
return
}
if (!claimFinalization()) return
cleanup()
logger.error(
{ component: 'ShellTool', errorCode: loggedCode },
'Shell command failed to start'
)
resolveOnce({
content:
errorCode === undefined
? 'Command failed to start'
: `Command failed to start: ${errorCode}`,
duration_ms: Date.now() - startTime,
is_error: true,
})
})
context?.signal?.addEventListener('abort', onAbort, { once: true })
if (context?.signal?.aborted) onAbort()
})
}
private managedRootUnavailable(startTime: number): ToolOutput {
return {
content:
'Managed shell unavailable: the verified caller workspace root is no longer canonical.',
duration_ms: Date.now() - startTime,
is_error: true,
}
}
}