Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* UnifiedApprovalGateController - LoopController that blocks tool calls
* for approval when the approval system is enabled.
*
* Handles BOTH MCP tools (identified by serverName__toolName convention)
* AND native tools with requiresApproval() == true (e.g., shell_exec, http_request).
*
* Used as the base delegate inside ApprovalController. The decorator chain:
* ApprovalController (checks auto_approved_tools → "proceed" if found)
* └─ UnifiedApprovalGateController (MCP tool? → suspend. Native requiresApproval? → suspend. Else → "proceed")
*
* This is the SINGLE approval gate (SPEC-UNIFIED §21). Gate 2 (the old
* tool.requiresApproval() check inside toolUseLoop) has been removed.
* All approval decisions go through this controller via LoopController.beforeTool().
*/
import { randomUUID } from 'node:crypto'
import { LoopController, Tool, ToolRegistry } from '../interfaces'
import { DefaultLoopController } from '../orchestration/loopConfig'
import { ChatMessage, PendingApproval, ToolDefinition } from '../types'
import type { ApprovalConfig } from './approvalTypes'
type NativeAwareRegistry = ToolRegistry & {
getNative?: (name: string) => ReturnType<ToolRegistry['get']>
}
/**
* Check whether a tool name follows the MCP naming convention.
* MCP tools are prefixed as: serverName__toolName (double underscore).
*/
export function isMcpToolName(toolName: string): boolean {
return toolName.includes('__')
}
/**
* Extract the MCP server prefix from a tool name.
* Returns null if the tool name is not an MCP tool.
*/
export function getMcpServerPrefix(toolName: string): string | null {
const idx = toolName.indexOf('__')
return idx >= 0 ? toolName.substring(0, idx) : null
}
// ─── U5 · Reactive OAuth-consent suspension ──────────────────────────────────
/** Typed `connect_required` marker carried on a tool result's metadata. */
export interface ConnectRequiredMarker {
mcpServerName: string
}
/**
* Read the typed `connect_required` marker off a tool result's `metadata`
* (set by `toolRegistryAdapter` when `manager.callTool` surfaced a 401 on an
* oauth mcp-server). Returns null for any other result — a plain error, a 403
* (terminal, never marked), or a non-oauth tool. Defensive against a malformed
* marker (missing mcpServerName → null) so a suspension is never raised without
* a server to connect.
*/
export function extractConnectRequiredMarker(
metadata: Record<string, unknown> | undefined
): ConnectRequiredMarker | null {
const raw = metadata?.connect_required
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
const marker = raw as Record<string, unknown>
const mcpServerName = typeof marker.mcpServerName === 'string' ? marker.mcpServerName : undefined
if (!mcpServerName) return null
return { mcpServerName }
}
/**
* Build a durable `connect_required` suspension for a tool call whose live
* execution surfaced a 401 on an oauth mcp-server (spec §U5). Reuses the SAME
* `PendingApproval` machinery as the HITL gate; `reason='connect_required'` +
* `mcpServerName` steers the desktop connect UI and is persisted so a
* cold restart never degrades this into a generic approval. The caller fills in
* `context_snapshot`/`completed_results`/`intent_summary` so the resume path
* re-executes the SAME tool once the user connects.
*/
export function buildConnectRequiredApproval(
call: { id: string; name: string; arguments: Record<string, unknown> },
marker: ConnectRequiredMarker
): PendingApproval {
return {
request_id: randomUUID(),
tool_name: call.name,
authorization_scope: 'exact_invocation',
tool_kind: 'mcp_server_tool',
// The authoritative server name is the marker's mcpServerName (set from the
// manager's sourceRef), mirroring the HITL gate's createSuspension
// (tool_source_ref = traceDescriptor.sourceRef). getMcpServerPrefix splits on
// the FIRST '__', so it truncates a server whose own name contains '__';
// reuse the marker to keep both suspension paths consistent (R3-L3).
tool_source_ref: marker.mcpServerName,
parameters: call.arguments,
description: `Connect ${marker.mcpServerName} to continue`,
tool_call_id: call.id,
context_snapshot: [],
reason: 'connect_required',
mcpServerName: marker.mcpServerName,
}
}
/**
* Cron×stateless approval prompt (product decision): creating or enabling a
* schedule on a stateless host keeps the pod running indefinitely (an active
* schedule blocks D8 suspension), so it is NEVER a fast/default action. The
* gate lives server-side at the single approval decision point — an
* LLM-settable `confirm` tool param was explicitly rejected as not model-proof.
*/
export const STATELESS_CRON_APPROVAL_PROMPT =
'Approve scheduled task on a stateless agent? While any schedule is active, this agent ' +
'stays running continuously and will NOT suspend when idle (higher cost). Remove or ' +
'disable the schedule to restore suspension.'
/** cron_manage actions that create or enable a schedule (gated on stateless hosts). */
const STATELESS_CRON_GATED_ACTIONS: ReadonlySet<string> = new Set(['create', 'enable'])
export class UnifiedApprovalGateController implements LoopController {
private readonly delegate = new DefaultLoopController()
/**
* ToolRegistry is REQUIRED (F2: Invariant 9) — ensures native tools with
* requiresApproval() are never silently skipped.
*
* approvalConfig is OPTIONAL — when provided, tools[name] overrides the
* tool's code default. Absent → fall through to tool.requiresApproval().
*/
constructor(
private readonly toolRegistry: ToolRegistry,
private readonly approvalConfig?: ApprovalConfig,
private readonly nativeToolRegistry?: ToolRegistry,
/**
* Cron×stateless options.
* - `statelessLifecycle` arms the cron_manage create/enable forced gate.
* - `cronManageGateOnly` (used for cron-SOURCED tasks) narrows the gate so
* ONLY that forced cron_manage check can suspend; every other tool call —
* MCP tools and native `requiresApproval()` tools alike — auto-proceeds,
* preserving issue #529's autonomous-cron carve-out. Without this the
* whole approval gate would re-engage for a cron run that has no human to
* answer it.
*/
private readonly options?: { statelessLifecycle?: boolean; cronManageGateOnly?: boolean }
) {}
shouldAccept(content: string, iteration: number): boolean {
return this.delegate.shouldAccept(content, iteration)
}
onTextRejected(content: string, iteration: number): ChatMessage | null {
return this.delegate.onTextRejected(content, iteration)
}
beforeTool(
toolName: string,
params: Record<string, unknown>
): 'proceed' | 'skip' | { type: 'suspend'; approval: PendingApproval } {
// Cron-SOURCED narrow gate: for a cron-fired task the only approval that may
// fire is the cron_manage create/enable forced gate (self-propagation
// containment — a schedule must not autonomously spawn/enable MORE
// schedules). Every other tool call keeps issue #529's autonomy and
// proceeds without a gate, so LIST/GET/DELETE/DISABLE/TRIGGER and all
// non-cron_manage work run unblocked.
if (this.options?.cronManageGateOnly === true) {
return this.forcedApproval(toolName, params) ?? 'proceed'
}
const registryWithNative = this.toolRegistry as NativeAwareRegistry
const nativeTool =
this.nativeToolRegistry?.get(toolName) ?? registryWithNative.getNative?.(toolName) ?? null
const tool = nativeTool ?? this.toolRegistry.get(toolName)
// 1. MCP tools always require approval (identified by naming convention),
// unless the composite registry resolves the name to a native Clerum tool.
if (isMcpToolName(toolName) && !nativeTool) {
return this.createSuspension(
toolName,
params,
`MCP tool "${toolName}" requires approval before execution`,
tool
)
}
// 1.5 Cron×stateless forced-approval gate: when stateless cron management
// is explicitly allowed, cron_manage CREATE/ENABLE must still run through
// HITL. Checked BEFORE the per-tool CRD override so
// `approval.tools["cron_manage"]: false` cannot waive it. Default-forbid
// hosts expose cron_manage for cleanup/observability, but the tool reports
// requiresApproval=false and rejects CREATE/ENABLE server-side.
const cronForced = this.forcedApproval(toolName, params)
if (cronForced) {
return cronForced
}
// 2. Native tools: CRD override > tool's code default.
// Use Object.hasOwn to avoid resolving prototype methods (e.g. tool name
// "toString" would otherwise hit Object.prototype.toString and produce a
// truthy "override").
const tools = this.approvalConfig?.tools
const override = tools && Object.hasOwn(tools, toolName) ? tools[toolName] : undefined
const needsApproval = override ?? tool?.requiresApproval() ?? false
if (needsApproval) {
return this.createSuspension(
toolName,
params,
`Tool "${toolName}" requires approval before execution`,
tool
)
}
// 3. No approval needed
return 'proceed'
}
onExhaustion(iteration: number): string {
return this.delegate.onExhaustion(iteration)
}
async refreshTools(currentTools: ToolDefinition[]): Promise<ToolDefinition[]> {
return this.delegate.refreshTools(currentTools)
}
/**
* Cron×stateless forced-approval gate (step 1.5). Returns a suspension only
* when stateless cron management is explicitly allowed and the registered
* tool still requires approval. Shared by the normal beforeTool path and the
* cron-sourced `cronManageGateOnly` path so both apply the same criterion.
* NOT waivable by the per-tool CRD override — it is checked before that
* override on both paths.
*
* Public so ApprovalController can consult it before any stored approval:
* every forced call asks, and no `'*'`, per-task, "always" or server-prefix
* approval covers it. The suspension is `exact_invocation`, so approving it
* authorizes only that frozen call.
*/
forcedApproval(
toolName: string,
params: Record<string, unknown>
): { type: 'suspend'; approval: PendingApproval } | null {
if (this.options?.statelessLifecycle === true && toolName === 'cron_manage') {
const registryWithNative = this.toolRegistry as NativeAwareRegistry
const tool =
this.nativeToolRegistry?.get(toolName) ??
registryWithNative.getNative?.(toolName) ??
this.toolRegistry.get(toolName)
if (tool?.requiresApproval() !== true) return null
const action = typeof params.action === 'string' ? params.action : ''
if (STATELESS_CRON_GATED_ACTIONS.has(action)) {
const suspension = this.createSuspension(
toolName,
params,
STATELESS_CRON_APPROVAL_PROMPT,
tool
)
return {
...suspension,
approval: { ...suspension.approval, authorization_scope: 'exact_invocation' },
}
}
}
return null
}
private createSuspension(
toolName: string,
params: Record<string, unknown>,
description: string,
tool: Tool | null
): { type: 'suspend'; approval: PendingApproval } {
const traceDescriptor = tool?.traceDescriptor?.(params) ?? {
kind: 'internal_tool' as const,
sourceRef: 'mcp-host',
}
const approval: PendingApproval = {
request_id: randomUUID(),
tool_name: toolName,
authorization_scope: 'turn_tools',
tool_kind: traceDescriptor.kind,
tool_source_ref: traceDescriptor.sourceRef,
parameters: params,
description,
tool_call_id: '', // Filled by toolUseLoop from call.id
context_snapshot: [],
}
return { type: 'suspend', approval }
}
}
/**
* @deprecated Use UnifiedApprovalGateController instead.
* Kept for backward compatibility during migration.
*/
export const McpApprovalGateController = UnifiedApprovalGateController