Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* Configuration settings loaded from environment variables.
*/
import { FILE_REFERENCE_MAX_COUNT } from '@clerum/gfs-interaction-policy'
import type { ApprovalConfig } from './core/extensions/approvalTypes'
import type { GuardrailsConfig } from './core/guardrails/config'
import { NativeToolConfig } from './core/interfaces'
import {
type CodexToolPresentation,
type NativeToolPresentation,
parseCodexToolDiscoveryBytes,
parseCodexToolPresentation,
parseNativeToolDiscoveryBytes,
parseNativeToolPresentation,
} from './core/orchestration/toolPresentationPolicy'
import { SHELL_TIMEOUT_CLEANUP_MS } from './core/tools/shellTimeouts'
import { ALL_PROVIDERS, type LlmProvider, descriptorFor, isLlmProvider } from './llm/registryCore'
import { logger } from './logger'
import type { McpCatalogBootstrapConfig } from './mcp/grantProbe'
import { HostSpec, McpServerInfo, MemoryConfig, ModelConfig, PersonalizationConfig } from './types'
/** Route families projected by WRC into a recipe-bound mcp-host. */
export const PLUGIN_WORKLOAD_SDK_CAPABILITIES = ['promptBridge', 'clientNotifications'] as const
export type PluginWorkloadSdkCapability = (typeof PLUGIN_WORKLOAD_SDK_CAPABILITIES)[number]
/**
* Parse the WRC capability projection without silently accepting typos. An
* empty/missing value is intentionally an empty set so the SDK activation gate
* fails closed rather than exposing a broader route surface than the recipe.
*/
export function parsePluginWorkloadSdkCapabilities(
raw: string | undefined
): PluginWorkloadSdkCapability[] {
if (!raw?.trim()) return []
const declared = raw
.split(',')
.map(value => value.trim())
.filter(Boolean)
const known = new Set<string>(PLUGIN_WORKLOAD_SDK_CAPABILITIES)
const unknown = declared.filter(value => !known.has(value))
if (unknown.length > 0) {
throw new Error(
`PLUGIN_WORKLOAD_SDK_CAPABILITIES contains unsupported value(s): ${unknown.join(', ')}`
)
}
return PLUGIN_WORKLOAD_SDK_CAPABILITIES.filter(capability => declared.includes(capability))
}
export interface Config {
// Dev mode - if true, reads config from env vars instead of K8s
devMode: boolean
// Dev mode config (parsed from CLERUM_HOST_CONFIG or built from env vars)
devHostConfig?: HostSpec
// Host name - used to find the Host CRD in production mode
hostName: string
// Kubernetes namespace
namespace: string
// Namespace where installed LlmHook workloads/Services live (spec §8.2). The
// guardrail hook resolver derives in-cluster endpoints against this namespace.
llmHooksNamespace: string
// Name of the operator-managed LLM allowlist ConfigMap watched by the
// ConfigStore (R3). Configurable so canary/test namespaces can point at a
// differently-named artifact; default matches the control-api writer.
llmAllowlistConfigMapName: string
// Dev mode: Model configuration from env vars
devModelProvider?: LlmProvider
devModelName?: string
// Default OFF. Codex provider construction stays dark until the operator
// sets MCP_HOST_CODEX_SUBSCRIPTION_ENABLED=true.
codexSubscriptionEnabled: boolean
// Server-owned Codex proxy URL. Callers cannot override this per request.
codexProxyRuntimeBaseUrl: string
grokSubscriptionEnabled: boolean
grokProxyRuntimeBaseUrl: string
grokPolicyRevision: number
grokPolicyHash: string
// Explicit authorize override for tests/dev. Host chat ignores an empty hash
// and binds policyRevision/policyHash from the allowlist ConfigMap instead.
codexPolicyRevision: number
codexPolicyHash: string
// Dev mode: MCP servers (parsed from CLERUM_MCP_SERVERS JSON)
devMcpServers?: McpServerInfo[]
// MCP Proxy mode (default: false — direct connection to MCP servers)
mcpProxyEnabled: boolean
// MCP Proxy URL (only used when mcpProxyEnabled is true)
mcpProxyUrl: string
// RPC Server port
serverPort: number
// Context Mapper URL (for fetching McpServers)
contextMapperUrl: string
// Context Mapper poll interval in ms (for production mode)
contextMapperPollInterval: number
// Maximum time an already-published MCP fleet may survive without a fresh,
// authenticated HCC inventory snapshot.
hccAuthorityMaxStalenessMs: number
// MCP server health heartbeat interval in ms. mcp-host periodically
// tools/list's each connected server to keep observedAt fresh and detect
// silent failures. Must stay well under the desktop's 120s stale threshold.
mcpStatusHeartbeatInterval: number
// Per-heartbeat round budget. A stalled MCP server must not retain the
// scheduler in-flight forever or cause overlapping rounds.
mcpStatusHeartbeatTimeoutMs: number
// Eager catalog-bootstrap probe policy. Bounds how often a user turn / the
// SHARED oauth-context gate asks control-api "does this grant exist?" so the
// probe cannot starve the host's own token issuance on the shared 60/min
// bucket. `enabled` is the kill-switch back to today's lazy admission.
mcpCatalogBootstrap: McpCatalogBootstrapConfig
// Agent configuration
agentTaskDelay: number
agentMaxTaskDuration: number
agentMaxToolCallsPerTask: number
agentMaxQueueSize: number
agentApprovalTimeout: number
// T2.1 — TTL for persisted pending approval rows (rows live in SQLite until
// a human resolves them; this caps how long an unresolved row survives a
// pod restart). Default 7d. Independent from `agentApprovalTimeout`
// (in-flight wait) and `spilloverTtlMs` (blob retention).
pendingApprovalTtlMs: number
// Approval system (default ON; tools advertise requiresApproval()).
enableApproval: boolean
// Dev-mode approval config parsed from CLERUM_APPROVAL_CONFIG; in prod the
// values come from the Host CRD.
approvalConfig?: ApprovalConfig
// Dev-mode guardrails config parsed from CLERUM_GUARDRAILS_CONFIG (spec §5); in
// prod the block comes from the Host CRD. Absent = no guardrails = today.
guardrailsConfig?: GuardrailsConfig
// Nudge controller (default OFF).
enableNudge: boolean
nudgeMaxIterations: number
// Context compaction: max token budget for the context window (default 100k)
contextMaxTokens: number
// P.2 — Tokenizer dry-run + offline knobs.
tokenizerDryrun: boolean
tokenizerOffline: boolean
// T1.4 — Anti-thrash for `PressureContextManager`.
compactionIneffectiveRatio: number
compactionIneffectiveMaxRun: number
// T1.2 — Pre-pruning before the LLM call. `compactionPrePruneEnabled` is
// the master flag (default true since #731); the four per-pass toggles
// exist for granular rollback.
compactionPrePruneEnabled: boolean
compactionPrePruneDedup: boolean
compactionPrePruneOneLine: boolean
compactionPrePruneJsonTruncate: boolean
compactionPrePruneStripMedia: boolean
compactionPrePruneMaxArgsBytes: number
compactionPrePruneSummaryTokens: number
compactionPrePruneProtectedTailTurns: number
// T1.1 — Structured summary template. Default OFF; flipped per-Host once
// the goldens prove parity / quality improvement in staging.
compactionStructuredSummary: boolean
// T2.2 — System-prompt cache flag (Anthropic prompt caching, tiered system
// prompt with <turn-context> moved to the user message).
promptCacheEnabled: boolean
// Codex presentation is independent of the legacy bridge opt-in.
codexToolPresentation: CodexToolPresentation
codexToolDiscoveryBytes: number
// #1003 — Native-tool presentation, independent of the Codex/Grok and legacy
// MCP presentation above. `auto` moves natives larger than the byte budget
// out of `tools[]` into search/describe/call; `direct` (default) keeps them.
nativeToolPresentation: NativeToolPresentation
nativeToolDiscoveryBytes: number
// F1 (dynamic-tool-loading) — Gates the dynamic-tool-loading bridge; default
// OFF; set true per-host to enable; see
// `.specs/dynamic-tool-loading/plan-hermes-bridge.es.md`.
dynamicToolsEnabled: boolean
// F1 (dynamic-tool-loading) — Minimum deferrable (MCP) tool count above which
// the bridge activates when enabled; small hosts stay on passthrough.
dynamicToolsThreshold: number
// T1.5 — Tool-result spillover. Master flag + threshold + TTL + GC period.
// When `toolSpilloverEnabled` is true the host wires a `SpilloverStorage`
// and TaskExecutor passes it to every loop; otherwise the loop ships
// inline content the way it did pre-T1.5.
toolSpilloverEnabled: boolean
toolSpilloverThresholdBytes: number
spilloverTtlMs: number
spilloverGcIntervalMs: number
// T2.1 — Conversation store backend selector and tuning knobs.
sessionStoreMode: 'memory' | 'sqlite' | 'dual'
/** Raw (lowercased) CLERUM_SESSION_STORE value, BEFORE the recognized-value
* check. The stateless-lifecycle boot guard aborts on an unrecognized raw
* value instead of accepting the silent 'memory' fallback (D3 §1.3b). */
sessionStoreModeRaw: string
sessionDbPath: string
/** D3 §1.2 — PVC-backed directory for state.db (CLERUM_SESSION_DB_DIR).
* When set, state.db lives at `${sessionDbDir}/state.db` and takes
* precedence over the workspace-derived path. */
sessionDbDir: string
/** D3 §1.1 — stateless agent lifecycle (CLERUM_STATELESS_LIFECYCLE).
* Activates the durability barrier and the fail-loud boot guard. */
statelessLifecycle: boolean
/** Stage 3 — push heartbeat cadence in ms
* (CLERUM_STATELESS_HEARTBEAT_INTERVAL_MS, default 30000). An explicitly
* set non-positive-integer value fails config load loudly. */
statelessHeartbeatIntervalMs: number
/** Stage 3 — pod UID from the Kubernetes downward API (CLERUM_POD_UID).
* HCC injects it via `fieldRef: metadata.uid` on stateless Hosts; empty
* when not injected (StatelessHeartbeat fails loud at construction). */
podUid: string
/** D3 §1.1 — explicit durability-barrier opt-in for always-on Hosts
* (CLERUM_DB_BARRIER_MODE=full). */
dbBarrierModeFull: boolean
conversationCacheSize: number
sessionTtlDays: number
dbWorkerHeartbeatMs: number
dbPersistSyncTimeoutMs: number
dbPersistAsyncTimeoutMs: number
dbWorkerStallTimeoutMs: number
dbCheckpointEveryWrites: number
dbWalSizeAlarmBytes: number
// T3.1 — Session search (clerum__session_search tool + REST endpoint).
// Master flag defaults OFF until staging soak confirms cross-user isolation.
// Retention controls the boot-time sweep of closed sessions; in-flight
// sessions are NEVER pruned (see T3.1-session-search.md §8).
sessionSearchEnabled: boolean
searchRetentionDays: number
// Native tool configuration
nativeTool: NativeToolConfig
// Attachment delivery configuration
enableResponseAttachments: boolean
attachmentMaxCount: number
attachmentMaxBytes: number
/**
* Decoded bytes per incoming `kind:'file'` attachment (issue #666). The
* default (11 MiB) matches the file quota of the chat body parser in
* `server.ts` and rpc-proxy (issue #678).
*/
attachmentFileMaxBytes: number
/** Bytes one `clerum__attachment_read` call may return (issue #666). */
attachmentTextReadMaxBytes: number
/**
* Structured file references one incoming message may carry (issue #666).
* The shared contract constant the Desktop composer also enforces; not
* operator-tunable, because the Desktop cannot observe a Host-only value.
*/
fileReferenceMaxCount: number
activityBufferSize: number
activityMaxEventBytes: number
// Memory (workspace) configuration.
memory: MemoryConfig
// Personalization configuration.
personalization: PersonalizationConfig
// Token budgets (P1) — pre-task budget check against control-api. Default OFF;
// the whole check path (BudgetClient construction + SessionProcessor wiring)
// is gated on this flag, and the check is fail-open (§0.2).
budgetsEnabled: boolean
// Governed tracing defaults ON; false skips best-effort tracing reporter wiring.
governedTracingEnabled: boolean
approvalPromptHistoryEnabled: boolean
approvalPromptHistoryMaxBytes: number
// Canonical process runtime. `workflowEnabled` is retained as a derived
// compatibility view for code that only needs the workflow yes/no answer;
// startup dispatch MUST use `runtimeKind` so sdk-only can never fall through
// to the standalone host.
runtimeKind: 'standalone' | 'workflow' | 'sdk-only'
// Workflow mode — derived from runtimeKind, never independently trusted.
workflowEnabled: boolean
workflowRecipeName: string
userApprovalRequestRecipeName: string
userApprovalRequestRecipeNamespace: string
workflowMaxIterations: number
// Auth configuration
enableAuth: boolean
authJwtPublicKey: string
authJwtIssuer: string
authJwtAudience: string
wrcPublicKey: string
// mcpHost runtime JWTs for workflow approval gating (optional; non-workflow mcp-hosts skip this)
// Also reused for LLM usage reporting → control-api via the same nginx gateway and JWT.
mcpHostRuntimeAccessToken?: string
mcpHostRuntimeRefreshToken?: string
mcpHostGatewayUrl?: string
mcpHostWorkflowControlToken?: string
mcpHostWorkflowControlTokenFile?: string
// ─── Plugin Workload SDK (promptBridge + clientNotifications) ──────
// The server starts only when the namespace-bound activation gate passes
// (flag + runtime JWT recipeNamespace + downward-API pod namespace, all
// fail-closed — see pluginWorkloadSdk/server/sdkServer.ts).
pluginWorkloadSdkEnabled: boolean
/** Exact capability families declared by WRC for this recipe-bound host. */
pluginWorkloadSdkCapabilities: PluginWorkloadSdkCapability[]
pluginWorkloadSdkRuntimeMode: 'workflow' | 'sdk-only'
pluginWorkloadSdkPort: number
/** Pod namespace via Kubernetes downward API (defense-in-depth). */
podNamespace: string
/** Overrides mcpHostGatewayUrl for SDK → control-api calls when set. */
pluginWorkloadSdkGatewayUrl?: string
/** WRC endpoint that redeems one signed prompt target ticket per attempt. */
pluginWorkloadSdkCredentialBrokerUrl: string
/** Recipe-scoped shared token workloads present to the SDK server. @deprecated use tokensDir */
pluginWorkloadSdkWorkloadToken?: string
/** Dev-only caller binding when using a single legacy workload token env var. */
pluginWorkloadSdkBoundCallerRef?: string
/** Directory of per-caller token files mounted from the recipe Secret. */
pluginWorkloadSdkWorkloadTokensDir?: string
pluginWorkloadSdkPromptTimeoutSeconds: number
pluginWorkloadSdkMaxConnections: number
pluginWorkloadSdkMaxConnectionsPerWorkload: number
pluginWorkloadSdkMaxRpmPerWorkload: number
pluginWorkloadSdkMaxLlmResponseBytes: number
}
function getEnv(key: string, defaultValue?: string): string | undefined {
return process.env[key] ?? defaultValue
}
/** 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: it reserves the shell's declared cleanup
* budget below the timer range. executeWithTimeout arms no cleanup timer for
* the shell (it joins abort settlement), but it rejects any timeout whose sum
* with that budget exceeds 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)
const minimum = allowZero ? 0 : 1
if (!/^\d+$/.test(raw) || !Number.isSafeInteger(value) || value < minimum || value > maximum) {
throw new Error(
`${key} must be a valid bounded integer from ${minimum} to ${maximum} (inclusive)`
)
}
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
return value.toLowerCase() === 'true' || value === '1'
}
function getEnvNumber(key: string, defaultValue: number): number {
const value = process.env[key]
if (!value) return defaultValue
const parsed = parseInt(value, 10)
// Guard against NaN and non-positive values — fall back to the default.
// Warn only when the value was actually set but invalid, so a typo'd env var
// is visible in logs rather than silently ignored.
if (!Number.isFinite(parsed) || parsed <= 0) {
logger.warn(
{ component: 'Config', configurationKey: key, defaultValue },
'Invalid positive integer configuration; using its default'
)
return defaultValue
}
return parsed
}
export type McpHostRuntimeKind = 'standalone' | 'workflow' | 'sdk-only'
/**
* Resolve the one authoritative startup kind from the two historical env
* signals. Explicit SDK/runtime mode and CLERUM_WORKFLOW_ENABLED must agree;
* contradictory combinations fail at config load instead of silently
* exposing workflow or standalone routes from an sdk-only Pod.
*/
export function resolveMcpHostRuntimeKind(input: {
workflowEnabled: boolean
pluginWorkloadSdkRuntimeMode?: string
}): McpHostRuntimeKind {
const rawMode = input.pluginWorkloadSdkRuntimeMode?.trim()
if (!rawMode) return input.workflowEnabled ? 'workflow' : 'standalone'
if (rawMode !== 'workflow' && rawMode !== 'sdk-only') {
throw new Error(
`Invalid PLUGIN_WORKLOAD_SDK_RUNTIME_MODE="${rawMode}"; expected workflow or sdk-only`
)
}
if (rawMode === 'workflow' && !input.workflowEnabled) {
throw new Error(
'Contradictory mcp-host runtime configuration: PLUGIN_WORKLOAD_SDK_RUNTIME_MODE=workflow requires CLERUM_WORKFLOW_ENABLED=true'
)
}
if (rawMode === 'sdk-only' && input.workflowEnabled) {
throw new Error(
'Contradictory mcp-host runtime configuration: PLUGIN_WORKLOAD_SDK_RUNTIME_MODE=sdk-only requires CLERUM_WORKFLOW_ENABLED=false'
)
}
return rawMode
}
/**
* Stage 3 (stateless-agents) — parse CLERUM_STATELESS_HEARTBEAT_INTERVAL_MS.
*
* Fail loud: an explicitly-set but non-positive-integer value THROWS at
* config load time (same posture as CLERUM_DB_BARRIER_MODE). A silent
* getEnvNumber-style fallback would let a typo'd cadence drive HCC's
* suspend decisions. Unset / empty returns the 30s default.
*/
export function parseStatelessHeartbeatIntervalMs(raw: string | undefined): number {
if (raw === undefined || raw.trim() === '') return 30_000
const parsed = Number(raw)
if (!Number.isInteger(parsed) || parsed <= 0) {
throw new Error(
`[Config] CLERUM_STATELESS_HEARTBEAT_INTERVAL_MS='${raw}' is not a positive integer`
)
}
return parsed
}
/**
* Parse CLERUM_DB_WORKER_STALL_TIMEOUT_MS, the longest time the db worker may
* go without completing an operation while it has work in flight. It must
* exceed the sync write timeout, so a sync write times out on its own budget
* before the worker is declared stalled. It must fit a Node timer (at most
* 2147483647 ms; a larger delay becomes 1 ms). An invalid value, the default
* included, fails at boot, as does a sync timeout that is not a positive
* integer.
*/
export function parseDbWorkerStallTimeoutMs(
raw: string | undefined,
syncTimeoutMs: number
): number {
if (!Number.isSafeInteger(syncTimeoutMs) || syncTimeoutMs <= 0) {
throw new Error(
`CLERUM_DB_PERSIST_SYNC_TIMEOUT_MS (${syncTimeoutMs}) must be a positive integer`
)
}
const name = 'CLERUM_DB_WORKER_STALL_TIMEOUT_MS'
const isDefault = raw === undefined || raw.trim() === ''
const label = isDefault ? "'30000' (default)" : `'${raw}'`
const value = isDefault ? 30_000 : /^\d+$/.test(raw) ? Number(raw) : NaN
if (!Number.isSafeInteger(value) || value < 1000) {
throw new Error(`${name}=${label} must be an integer of at least 1000`)
}
if (value > 2_147_483_647) {
throw new Error(`${name}=${label} must not exceed 2147483647`)
}
if (value <= syncTimeoutMs) {
throw new Error(
`${name}=${label} must exceed CLERUM_DB_PERSIST_SYNC_TIMEOUT_MS (${syncTimeoutMs})`
)
}
return value
}
/**
* Parse an MCP status-heartbeat duration. These values participate in the
* liveness scheduler, so an explicit typo must fail at boot rather than turn
* into an unbounded timer or a silent fallback.
*/
export function parseMcpStatusHeartbeatDuration(
name: string,
raw: string | undefined,
defaultValue: number
): number {
if (raw === undefined || raw.trim() === '') return defaultValue
if (!/^\d+$/.test(raw)) {
throw new Error(`[Config] ${name}='${raw}' is not a positive safe integer`)
}
const value = Number(raw)
if (!Number.isSafeInteger(value) || value <= 0) {
throw new Error(`[Config] ${name}='${raw}' is not a positive safe integer`)
}
return value
}
/**
* Parse CLERUM_HOST_CONFIG JSON for dev mode.
*/
function parseDevHostConfig(): HostSpec | undefined {
const configJson = process.env.CLERUM_HOST_CONFIG
if (!configJson) {
return undefined
}
try {
const parsed = JSON.parse(configJson) as HostSpec
logger.info(
{ component: 'Config', modelConfigured: !!parsed.model },
'Parsed dev Host configuration'
)
return parsed
} catch (error) {
// A JSON.parse SyntaxError quotes a slice of the input; log its name only.
logger.error(
{ component: 'Config', errorName: (error as SyntaxError).name },
'Failed to parse dev Host configuration'
)
return undefined
}
}
/**
* Build dev host config from individual environment variables. The default
* model per provider comes straight from the registry descriptor.
*/
function getDefaultModel(provider: LlmProvider): string {
const model = descriptorFor(provider).defaultModel
if (!model) {
throw new Error(`[Config] provider '${provider}' requires an explicit model`)
}
return model
}
function buildDevHostConfig(provider?: LlmProvider, modelName?: string): HostSpec {
const model: ModelConfig | undefined = provider
? {
provider,
name: modelName || getDefaultModel(provider),
}
: undefined
logger.info(
{ component: 'Config', modelConfigured: !!model },
'Built dev Host configuration from environment'
)
return {
host: 'dev-host',
contextRef: 'dev-context',
secretRef: 'dev-secret',
model,
}
}
const devMode = getEnvBool('CLERUM_DEV_MODE', false)
// Read once: the top-level field documents the limit, `nativeTool` carries it
// to `clerum__attachment_read` (#666). A page is shipped inline (the tool is
// spillover-exempt). Its byte ceiling is separate from the measured page and
// turn token budgets: dense data and output wrapping invalidate a fixed ratio.
const attachmentTextReadMaxBytes = getExecutionLimit(
'CLERUM_ATTACHMENT_TEXT_READ_MAX_BYTES',
65_536,
false,
1_048_576
)
const attachmentFileMaxBytes = getExecutionLimit(
'CLERUM_ATTACHMENT_FILE_MAX_BYTES',
11_534_336,
false,
11_534_336
)
const configuredWorkflowEnabled = getEnvBool('CLERUM_WORKFLOW_ENABLED', false)
const configuredRuntimeKind = resolveMcpHostRuntimeKind({
workflowEnabled: configuredWorkflowEnabled,
pluginWorkloadSdkRuntimeMode: getEnv('PLUGIN_WORKLOAD_SDK_RUNTIME_MODE'),
})
// Raw CLERUM_MODEL_PROVIDER env var. NOT validated here: this runs at module top
// level (imported very early, in prod too), so a stray/invalid value must never
// throw on import. Validation is deferred to the dev-only path via
// resolveDevModelProvider().
const rawDevModelProvider = getEnv('CLERUM_MODEL_PROVIDER')
const devModelName = getEnv('CLERUM_MODEL_NAME')
/**
* Narrow a raw CLERUM_MODEL_PROVIDER value to an `LlmProvider`.
*
* Fail-closed: an explicitly-set but unknown provider THROWS rather than
* dropping to undefined. Dropping it would silently fall through to API-key
* auto-detection — routing to a different provider and ignoring
* CLERUM_MODEL_NAME, a provider-boundary regression. An ABSENT value returns
* undefined (auto-detection is the intended fallback there).
*
* MUST only be called from the dev-only path (after the devMode guard) so it
* never throws at module top level in prod.
*/
export function resolveDevModelProvider(raw: string | undefined): LlmProvider | undefined {
if (!raw) return undefined
if (!isLlmProvider(raw)) {
throw new Error(
`Invalid CLERUM_MODEL_PROVIDER '${raw}'. Valid providers: ${ALL_PROVIDERS.join(', ')}`
)
}
return raw
}
/**
* Keep the poll cadence strictly inside the authority-retention window.
*
* A cadence at or above the staleness ceiling guarantees that a healthy fleet
* can be revoked before the next authoritative poll arrives. Failing startup
* closed is safer than silently widening the retention window or allowing a
* deployment to flap forever after every successful reconnect.
*/
export function validateHccAuthorityTiming(
contextMapperPollIntervalMs: number,
hccAuthorityMaxStalenessMs: number
): void {
if (
Number.isFinite(contextMapperPollIntervalMs) &&
Number.isFinite(hccAuthorityMaxStalenessMs) &&
contextMapperPollIntervalMs >= hccAuthorityMaxStalenessMs
) {
throw new Error(
`CLERUM_CONTEXT_MAPPER_POLL_INTERVAL (${contextMapperPollIntervalMs}ms) must be less than HCC_AUTHORITY_MAX_STALENESS_MS (${hccAuthorityMaxStalenessMs}ms)`
)
}
}
/**
* Parse one positive-integer knob, failing startup closed on a set-but-invalid
* value rather than silently falling back — a mistyped probe budget must be
* visible at boot, not degrade the shared rate-limit bucket in production.
*/
function parseBootstrapNumber(key: string, defaultValue: number, min = 1): number {
const raw = process.env[key]
const value = raw === undefined ? defaultValue : Number(raw)
if (!Number.isFinite(value) || value < min) {
throw new Error(`${key} must be a finite number >= ${min} (got '${raw}')`)
}
return value
}
// control-api rate-limits `user-token` AND `grants/exists` under one shared
// `mcp_oauth_broker` bucket (default 60/min per host). If the per-turn probe
// budget could reach that ceiling, probes alone could starve token issuance —
// the exact host self-DoS this module exists to prevent. Guard against an
// operator setting probesPerMin at or above the bucket; mirrors control-api's
// CONTROL_API_OAUTH_BROKER_RL_PER_MIN default.
const OAUTH_BROKER_SHARED_BUCKET_PER_MIN = 60
/**
* Build the eager catalog-bootstrap probe policy from env. Fail-fast on a probe
* timeout that meets or exceeds the wait budget: a probe slower than the whole
* turn budget can never complete in time, so the config is nonsensical.
*/
export function buildMcpCatalogBootstrapConfig(): McpCatalogBootstrapConfig {
const cfg: McpCatalogBootstrapConfig = {
enabled: getEnvBool('MCP_CATALOG_BOOTSTRAP_ENABLED', true),
waitBudgetMs: parseBootstrapNumber('MCP_CATALOG_BOOTSTRAP_WAIT_BUDGET_MS', 4000),
probeTimeoutMs: parseBootstrapNumber('MCP_CATALOG_BOOTSTRAP_PROBE_TIMEOUT_MS', 2000),
connectTimeoutMs: parseBootstrapNumber('MCP_CATALOG_BOOTSTRAP_CONNECT_TIMEOUT_MS', 8000),
negativeTtlMs: parseBootstrapNumber('MCP_CATALOG_BOOTSTRAP_NEGATIVE_TTL_MS', 15000),
failureTtlMs: parseBootstrapNumber('MCP_CATALOG_BOOTSTRAP_FAILURE_TTL_MS', 60000),
probesPerMin: parseBootstrapNumber('MCP_CATALOG_BOOTSTRAP_PROBES_PER_MIN', 20),
backoffMs: parseBootstrapNumber('MCP_CATALOG_BOOTSTRAP_BACKOFF_MS', 30000),
}
if (cfg.probeTimeoutMs >= cfg.waitBudgetMs) {
throw new Error(
`MCP_CATALOG_BOOTSTRAP_PROBE_TIMEOUT_MS (${cfg.probeTimeoutMs}ms) must be less than MCP_CATALOG_BOOTSTRAP_WAIT_BUDGET_MS (${cfg.waitBudgetMs}ms)`
)
}
if (cfg.probesPerMin >= OAUTH_BROKER_SHARED_BUCKET_PER_MIN) {
throw new Error(
`MCP_CATALOG_BOOTSTRAP_PROBES_PER_MIN (${cfg.probesPerMin}) must be less than the shared mcp_oauth_broker bucket (${OAUTH_BROKER_SHARED_BUCKET_PER_MIN}/min) so probes cannot starve user-token issuance`
)
}
return cfg
}
// In dev mode, try CLERUM_HOST_CONFIG first, then fall back to building from env vars
function getDevHostConfig(): HostSpec | undefined {
if (!devMode) return undefined
const fromJson = parseDevHostConfig()
if (fromJson) return fromJson
return buildDevHostConfig(resolveDevModelProvider(rawDevModelProvider), devModelName)
}
/**
* Parse CLERUM_MCP_SERVERS JSON for dev mode.
* Format: a flat McpServerInfo[] — [{"name": "...", "contextRef": "...", "transport": {...}}]
* (no `spec` wrapper; the parsed JSON is used as-is, without shape validation).
*/
function parseDevMcpServers(): McpServerInfo[] | undefined {
const serversJson = process.env.CLERUM_MCP_SERVERS
if (!serversJson) {
return undefined
}
try {
const parsed = JSON.parse(serversJson) as McpServerInfo[]
logger.info({ component: 'Config', serverCount: parsed.length }, 'Parsed dev MCP servers')
return parsed
} catch (error) {
logger.error(
{ component: 'Config', errorName: (error as SyntaxError).name },
'Failed to parse dev MCP servers'
)
return undefined
}
}
/**
* Parse CLERUM_APPROVAL_CONFIG JSON for dev mode.
* Format: {"defaultPolicy":"designated_approvers","channels":{"telegram":{"enabled":true,"approvers":["123"]}}}
*/
/** Parse CLERUM_GUARDRAILS_CONFIG JSON for dev mode (the `Host.spec.guardrails` block, spec §5). */
function parseGuardrailsConfig(): GuardrailsConfig | undefined {
const configJson = process.env.CLERUM_GUARDRAILS_CONFIG
if (!configJson) return undefined
try {
const parsed = JSON.parse(configJson) as GuardrailsConfig
logger.info(
{ component: 'Config', ruleCount: parsed.rules?.length ?? 0 },
'Parsed guardrails configuration'
)
return parsed
} catch (error) {
logger.error(
{ component: 'Config', errorName: (error as SyntaxError).name },
'Failed to parse guardrails configuration'
)
return undefined
}
}
function parseApprovalConfig(): ApprovalConfig | undefined {
const configJson = process.env.CLERUM_APPROVAL_CONFIG
if (!configJson) {
return undefined
}
try {
const parsed = JSON.parse(configJson) as ApprovalConfig
logger.info(
{ component: 'Config', channelCount: Object.keys(parsed.channels || {}).length },
'Parsed approval configuration'
)
return parsed
} catch (error) {
logger.error(
{ component: 'Config', errorName: (error as SyntaxError).name },
'Failed to parse approval configuration'
)
return undefined
}
}
function parseApprovalPromptHistoryMaxBytes(raw: string): number {
if (!/^(?:0|[1-9][0-9]*)$/.test(raw)) return Number.NaN
const value = Number(raw)
return Number.isSafeInteger(value) && value >= 1_024 && value <= 32_768 ? value : Number.NaN
}
const contextMapperPollInterval = parseInt(
getEnv('CLERUM_CONTEXT_MAPPER_POLL_INTERVAL', '30000')!,
10
)
// Fail-closed window for an UNREACHABLE HCC (5xx / transport failures only).
// It is bounded so a revoked-but-unconfirmable authority cannot linger forever,
// yet generous enough to survive a normal HCC `Recreate` rollout (measured ~77s
// in clerum-dev, with a startupProbe budget of up to 120s) without tearing down
// the whole MCP fleet and aborting in-flight tool calls.
//
// Crucially, this window ONLY governs the `unavailable` failure class. Identity /
// authorization failures (401/403 — Host UID change, revoked grant) revoke
// immediately on the next reachable call, and a grant change while HCC is healthy
// is applied by the next successful poll. Raising this ceiling intentionally trades
// bounded revocation latency during an HCC outage for fleet availability; it does
// not widen the NP-08 credential-disclosure surface because HCC cannot serve a new
// credential while unavailable and rechecks live authorization when reachable.
// See issue #425.
//
// Operators may lower it, or raise it up to HCC_AUTHORITY_MAX_STALENESS_CEILING_MS
// for slower-starting clusters. The minikube e2e lane pins 60000 explicitly so the
// revoke-on-staleness scenario stays fast and deterministic.
const HCC_AUTHORITY_MAX_STALENESS_CEILING_MS = 600_000 // 10 min hard upper bound
const hccAuthorityMaxStalenessMs = Math.min(
getEnvNumber('HCC_AUTHORITY_MAX_STALENESS_MS', 180_000),
HCC_AUTHORITY_MAX_STALENESS_CEILING_MS
)
// Dev mode does not retain a Kubernetes-authoritative MCP fleet, so the
// production polling/staleness relationship is intentionally not required for
// local fixture runs. Every cluster-mode process must satisfy it at startup.
if (!devMode) validateHccAuthorityTiming(contextMapperPollInterval, hccAuthorityMaxStalenessMs)
export const config: Config = {
devMode,
devHostConfig: getDevHostConfig(),
// Host name (required in production mode)
hostName:
process.env.CLERUM_HOST_NAME ||
(devMode || process.env.NODE_ENV !== 'production'
? 'dev-host'
: (() => {
throw new Error('Missing required environment variable: CLERUM_HOST_NAME')
})()),
// Kubernetes namespace
namespace: getEnv('CLERUM_NAMESPACE', 'default')!,
// Namespace where installed LlmHook workloads/Services live (spec §8.2).
llmHooksNamespace: getEnv('CLERUM_LLM_HOOKS_NAMESPACE', 'llm-hooks')!,
// LLM allowlist ConfigMap name (R3). CROSS-SERVICE CONTRACT: the default
// (`clerum-llm-allowed-models`) is the CM produced by control-api
// (control-api/src/services/llmAllowedModelsConfigMap.ts) and also read by WRC
// (workflow-recipes/src/workflow/modelConfigHandler.ts). The env override is a
// canary/test knob for THIS mcp-host only — pointing it at a CM control-api does
// not write breaks the allowlist seam (the Host then sees no allowed models).
llmAllowlistConfigMapName: getEnv('CLERUM_LLM_ALLOWED_MODELS_CM', 'clerum-llm-allowed-models')!,
// Dev mode model config. Provider is validated (and only resolved) in dev mode;
// resolveDevModelProvider fail-closes on a set-but-invalid value.
devModelProvider: devMode ? resolveDevModelProvider(rawDevModelProvider) : undefined,
devModelName,
codexSubscriptionEnabled: process.env.MCP_HOST_CODEX_SUBSCRIPTION_ENABLED === 'true',
codexProxyRuntimeBaseUrl: getEnv(
'CODEX_LLM_PROXY_RUNTIME_URL',
'http://codex-llm-proxy.control-plane.svc.cluster.local:8080'
)!,
// Empty hash is not a grant: Host chat computes the per-model digest from
// clerum.io/catalog-revision + clerum.io/connection-revision on the allowlist
// ConfigMap. Set both env vars together only as a test/dev override.
codexPolicyRevision: parseInt(getEnv('CODEX_POLICY_REVISION', '1')!, 10),
codexPolicyHash: getEnv('CODEX_POLICY_HASH', '')!,
grokSubscriptionEnabled: process.env.MCP_HOST_GROK_SUBSCRIPTION_ENABLED === 'true',
grokProxyRuntimeBaseUrl: getEnv(
'GROK_LLM_PROXY_RUNTIME_URL',
'http://grok-llm-proxy.control-plane.svc.cluster.local:8080'
)!,
grokPolicyRevision: parseInt(getEnv('GROK_POLICY_REVISION', '1')!, 10),
grokPolicyHash: getEnv('GROK_POLICY_HASH', '')!,
// Dev mode MCP servers
devMcpServers: devMode ? parseDevMcpServers() : undefined,
// MCP Proxy: feature flag + URL (default: off, direct connection to each MCP server)
mcpProxyEnabled: getEnvBool('MCP_PROXY_ENABLED', false),
mcpProxyUrl: getEnv(
'MCP_PROXY_URL',
devMode ? 'http://localhost:8083' : 'http://mcp-proxy.mcp-server.svc.cluster.local:8083'
)!,
// RPC Server port
serverPort: parseInt(getEnv('CLERUM_SERVER_PORT', '8080')!, 10),
// Host Context Controller URL (defaults based on mode)
contextMapperUrl: getEnv(
'CLERUM_CONTEXT_MAPPER_URL',
devMode
? 'http://localhost:8081'
: 'http://host-context-controller-api-gateway.control-plane.svc.cluster.local:8081'
)!,
// Context Mapper poll interval (default 30 seconds)
contextMapperPollInterval,
// Bound transient HCC/Kubernetes authority outages. Identity failures revoke
// immediately; 5xx/transport failures may preserve the last good fleet only
// within this finite window.
hccAuthorityMaxStalenessMs,
// MCP status heartbeat. Defaults to 30 seconds so a single missed tick does
// not trip desktop staleness.
mcpStatusHeartbeatInterval: parseMcpStatusHeartbeatDuration(
'CLERUM_MCP_STATUS_HEARTBEAT_INTERVAL',
getEnv('CLERUM_MCP_STATUS_HEARTBEAT_INTERVAL'),
30_000
),
mcpStatusHeartbeatTimeoutMs: parseMcpStatusHeartbeatDuration(
'CLERUM_MCP_STATUS_HEARTBEAT_TIMEOUT_MS',
getEnv('CLERUM_MCP_STATUS_HEARTBEAT_TIMEOUT_MS'),
25_000
),
// Agent configuration
agentTaskDelay: getExecutionLimit('CLERUM_AGENT_TASK_DELAY', 3, true),
agentMaxTaskDuration: getExecutionLimit('CLERUM_AGENT_MAX_TASK_DURATION', 86400000),
agentMaxToolCallsPerTask: getExecutionLimit('CLERUM_AGENT_MAX_TOOL_CALLS', 1000),
agentMaxQueueSize: parseInt(getEnv('CLERUM_AGENT_MAX_QUEUE_SIZE', '100')!, 10),
// 0 = disabled (default): an unresolved approval never auto-denies in memory,
// so the request stays available no matter how long the human takes. A
// suspended session only blocks its OWN session's next tasks (it frees the
// global concurrency slot in SessionProcessor), and the durable pending row is
// still bounded by `pendingApprovalTtlMs` (7d) + the boot-time reaper.
agentApprovalTimeout: parseInt(getEnv('CLERUM_APPROVAL_TIMEOUT', '0')!, 10),
pendingApprovalTtlMs:
parseInt(getEnv('CLERUM_PENDING_APPROVAL_TTL_HOURS', '168')!, 10) * 3600 * 1000, // 7d default
// Workflow step iteration limit — max LLM↔tool rounds per step before forced wrap-up.
// Override per step via CRD spec.steps[].maxIterations. Default 50.
workflowMaxIterations: parseInt(getEnv('CLERUM_WORKFLOW_MAX_ITERATIONS', '50')!, 10),
// Approval system (default ON; tools advertise requiresApproval()).
enableApproval: getEnvBool('CLERUM_ENABLE_APPROVAL', true),
// Dev-mode override; in prod the values come from the Host CRD.
approvalConfig: parseApprovalConfig(),
guardrailsConfig: parseGuardrailsConfig(),
// Nudge controller (default OFF).
enableNudge: getEnvBool('CLERUM_ENABLE_NUDGE', false),
nudgeMaxIterations: parseInt(getEnv('CLERUM_NUDGE_MAX_ITERATIONS', '3')!, 10),
// Context compaction: max token budget (default 100k, configurable via CLERUM_CONTEXT_MAX_TOKENS)
//
// IronClaw invariant #1 (P.3 §4.1): compaction is skipped while a session
// has `pending_approval`. The token-budget threshold is not relaxed — the
// loop simply emits `compaction:skipped` and lets the snapshot survive
// verbatim. The session unblocks once the user approves/denies.
//
// Approval timeouts and the new `approval_expired` route are INDEPENDENT
// failure modes (P.3 §4.4):
// - `AgentConfig.approvalTimeout` ticks from registerApproval; on expiry
// the executor is auto-denied with `reason='approval_timeout'`.
// - `approval_expired` fires only on resume, when a spillover ref in the
// snapshot is gone. The user clicked Approve in time — the underlying
// data simply no longer exists. T1.5 will add CLERUM_SPILLOVER_TTL_HOURS
// to govern that lifetime.
//
// The budget divides every pressure ratio: a NaN or 0 would make every
// threshold check meaningless, so anything but a positive integer stops
// the Host here (R9-15).
contextMaxTokens: getExecutionLimit('CLERUM_CONTEXT_MAX_TOKENS', 100000),
// P.2 — Tokenizer dry-run. When true (default during the bake-week), the
// PressureContextManager computes both the heuristic and the real counter
// values for every decision, but USES the heuristic to choose the tier.
// Provides observability via `clerum_tokenizer_dryrun_delta` /
// `clerum_tokenizer_dryrun_tier_mismatch_total` without changing behavior.
// Flip to false (default after recalibration) once the new thresholds land.
tokenizerDryrun: getEnvBool('CLERUM_TOKENIZER_DRYRUN', true),
// When true the AnthropicTokenCounter skips its network call and returns the
// heuristic upper bound instead.
//
// Defaults to TRUE so the default config makes ZERO network calls on the hot
// path (legacy/safe). With offline=false + dryRun=true, `computePressure`
// would fire a real `beta.messages.countTokens` round-trip on EVERY manage()
// (~2×/loop iteration) for Claude hosts — added latency + rate-limit pressure
// purely to compute a dry-run delta that does not change the tier decision.
// Operators flip this to false deliberately for the recalibration bake-week,
// accepting the network cost while watching the rate-limit metric.
tokenizerOffline: getEnvBool('CLERUM_TOKENIZER_OFFLINE', true),
// T1.4 — Anti-thrash. If a compaction reduces tokens by less than this
// fraction (`ratio = post/pre > 0.9` ≈ ≤10% saved), it counts as ineffective.
// After `compactionIneffectiveMaxRun` consecutive ineffective compactions
// the PressureContextManager stops compacting until the task ends, leaving
// the existing task-level budgets to wrap things up cleanly. Defaults match
// Hermes (`.specs/mcp-hermes/1-diagnostic-hermes.md` §8 / §13).
compactionIneffectiveRatio: parseFloat(getEnv('CLERUM_COMPACTION_INEFFECTIVE_RATIO', '0.9')!),
compactionIneffectiveMaxRun: parseInt(getEnv('CLERUM_COMPACTION_INEFFECTIVE_MAX_RUN', '2')!, 10),
// T1.2 — Pre-pruning. Master flag defaults ON since #731 (2026-09-22): the
// rollout it was waiting on never happened, and no manifest in the repo sets
// the variable, so the code default is what every Host actually runs.
// `CLERUM_COMPACTION_PRE_PRUNE=false` remains the kill switch, and the
// per-pass toggles below still default ON so operators can flip them all at
// once with the master. See
// `.specs/mcp-hermes/implementation-plans/T1.2-pre-pruning.md` §9.
compactionPrePruneEnabled: getEnvBool('CLERUM_COMPACTION_PRE_PRUNE', true),
compactionPrePruneDedup: getEnvBool('CLERUM_COMPACTION_PRE_PRUNE_DEDUP', true),
compactionPrePruneOneLine: getEnvBool('CLERUM_COMPACTION_PRE_PRUNE_ONE_LINE', true),
compactionPrePruneJsonTruncate: getEnvBool('CLERUM_COMPACTION_PRE_PRUNE_JSON_TRUNC', true),
compactionPrePruneStripMedia: getEnvBool('CLERUM_COMPACTION_PRE_PRUNE_STRIP_MEDIA', true),
compactionPrePruneMaxArgsBytes: parseInt(
getEnv('CLERUM_COMPACTION_PRE_PRUNE_TRUNCATE_BYTES', '4096')!,
10
),
compactionPrePruneSummaryTokens: parseInt(
getEnv('CLERUM_COMPACTION_PRE_PRUNE_SUMMARY_TOKENS', '200')!,
10
),
compactionPrePruneProtectedTailTurns: parseInt(
getEnv('CLERUM_COMPACTION_PROTECTED_TAIL_TURNS', '3')!,
10
),
// T1.1 — Structured summary template. Default OFF until staging confirms
// parse-ok rate ≥ 80% on the LLM in use.
compactionStructuredSummary: getEnvBool('CLERUM_COMPACTION_STRUCTURED_SUMMARY', false),
// T2.2 — System-prompt cache. ENABLED by default since 2026-06-23 (was OFF
// pending an Anthropic canary that never ran; shipped on + monitored instead).
// ROLLBACK: set CLERUM_PROMPT_CACHE_ENABLED=false (per-process env, no code
// change) on any host if a regression is observed.
// When ON, `TaskExecutor.buildLoopConfig` builds tiered `SystemPromptParts`
// via `PromptCache.getOrBuild`, plumbs them through `ReasoningPort` and
// `LlmPortAdapter`, and the Anthropic provider emits `cache_control`. For
// providers without explicit cache markers (OpenAI / ZAI / Bailian) the
// parts are concatenated back into a single `system` string (no native
// caching, but the tiered build path is used uniformly).
promptCacheEnabled: getEnvBool('CLERUM_PROMPT_CACHE_ENABLED', true),
// Codex optimization is independent of the legacy dynamic-tools opt-in.
codexToolPresentation: parseCodexToolPresentation(process.env.CODEX_TOOL_PRESENTATION),
codexToolDiscoveryBytes: parseCodexToolDiscoveryBytes(process.env.CODEX_TOOL_DISCOVERY_BYTES),
nativeToolPresentation: parseNativeToolPresentation(process.env.CLERUM_NATIVE_TOOL_PRESENTATION),
nativeToolDiscoveryBytes: parseNativeToolDiscoveryBytes(
process.env.CLERUM_NATIVE_TOOL_DISCOVERY_BYTES
),
// Legacy dynamic tools remain opt-in for other providers.
dynamicToolsEnabled: getEnvBool('CLERUM_DYNAMIC_TOOLS_ENABLED', false),
// F1 (dynamic-tool-loading) — Minimum deferrable (MCP) tool count above which
// the bridge activates when enabled; small hosts stay on passthrough.
dynamicToolsThreshold: getEnvNumber('CLERUM_DYNAMIC_TOOLS_THRESHOLD', 60),
// T2.1 — Conversation store backend selector.
//
// - `memory`: legacy InMemoryConversationStore (no durability). Default
// for a process started outside HCC (local dev, tests). HCC sets
// `CLERUM_SESSION_STORE=sqlite` in every Host container's env, which
// wins over the mcp-host ConfigMap (docs/architecture/host-storage-layout.md).
// - `sqlite`: SqliteConversationStore (RAM + worker thread + state.db).
// - `dual`: both stores live, reads from RAM, writes apply to both —
// for one-week parity validation (`clerum_conversation_store_parity_total`).
//
// See `.specs/mcp-hermes/implementation-plans/T2.1-sqlite-store.md` §10.
sessionStoreMode: (() => {
const raw = (getEnv('CLERUM_SESSION_STORE', 'memory') || 'memory').toLowerCase()
if (raw === 'memory' || raw === 'sqlite' || raw === 'dual') {
return raw as 'memory' | 'sqlite' | 'dual'
}
logger.warn(
{ component: 'Config', configurationKey: 'CLERUM_SESSION_STORE', selectedMode: 'memory' },
'Unknown session store mode; using memory'
)
return 'memory' as const
})(),
sessionStoreModeRaw: (getEnv('CLERUM_SESSION_STORE', 'memory') || 'memory').toLowerCase(),
sessionDbPath: getEnv('CLERUM_SESSION_DB_PATH', '') || '',
sessionDbDir: getEnv('CLERUM_SESSION_DB_DIR', '') || '',
statelessLifecycle: getEnvBool('CLERUM_STATELESS_LIFECYCLE', false),
statelessHeartbeatIntervalMs: parseStatelessHeartbeatIntervalMs(
getEnv('CLERUM_STATELESS_HEARTBEAT_INTERVAL_MS')
),
// Stage 3 — Kubernetes downward API pod UID. Empty when the operator has
// not injected it; StatelessHeartbeat fails loud at construction when the
// stateless lifecycle needs it.
podUid: getEnv('CLERUM_POD_UID', '') || '',
// D3 §1.1 — explicit env opt-in for the fsync barrier on always-on Hosts.
// Accepted values: '' (unset), 'normal', 'full'. Anything else is a config
// error and fails loud at load time — a typo must not silently disable the
// durability the operator asked for.
dbBarrierModeFull: (() => {
const raw = (getEnv('CLERUM_DB_BARRIER_MODE', '') || '').toLowerCase()
if (raw === '' || raw === 'normal') return false
if (raw === 'full') return true
throw new Error(
`[Config] CLERUM_DB_BARRIER_MODE='${raw}' is not recognized (expected 'full' or 'normal')`
)
})(),
conversationCacheSize: parseInt(getEnv('CLERUM_CONVERSATION_CACHE_SIZE', '200')!, 10),
sessionTtlDays: parseInt(getEnv('CLERUM_SESSION_TTL_DAYS', '90')!, 10),
dbWorkerHeartbeatMs: parseInt(getEnv('CLERUM_DB_WORKER_HEARTBEAT_MS', '5000')!, 10),
dbPersistSyncTimeoutMs: parseInt(getEnv('CLERUM_DB_PERSIST_SYNC_TIMEOUT_MS', '2000')!, 10),
dbPersistAsyncTimeoutMs: parseInt(getEnv('CLERUM_DB_PERSIST_ASYNC_TIMEOUT_MS', '5000')!, 10),
dbWorkerStallTimeoutMs: parseDbWorkerStallTimeoutMs(
getEnv('CLERUM_DB_WORKER_STALL_TIMEOUT_MS', ''),
parseInt(getEnv('CLERUM_DB_PERSIST_SYNC_TIMEOUT_MS', '2000')!, 10)
),
dbCheckpointEveryWrites: parseInt(getEnv('CLERUM_DB_CHECKPOINT_EVERY_WRITES', '100')!, 10),
dbWalSizeAlarmBytes: parseInt(getEnv('CLERUM_DB_WAL_SIZE_ALARM_BYTES', '52428800')!, 10),
// T3.1 — `clerum__session_search` tool + REST. Default OFF: must be flipped
// on per-Host once staging soak validates cross-user isolation (test #18).
// Retention controls the boot-only sweep; defaults to 90 days per spec §8.
sessionSearchEnabled: getEnvBool('CLERUM_SESSION_SEARCH_ENABLED', false),
searchRetentionDays: parseInt(getEnv('CLERUM_SEARCH_RETENTION_DAYS', '90')!, 10),
// T1.5 — Tool-result spillover. Master flag defaults ON (the feature is
// backward-safe: outputs under the threshold are unchanged). Set to false
// to disable persistence entirely; the loop falls back to the pre-T1.5
// path (full content inline).
toolSpilloverEnabled: getEnvBool('CLERUM_TOOL_SPILLOVER_ENABLED', true),
toolSpilloverThresholdBytes: getExecutionLimit('CLERUM_TOOL_SPILLOVER_THRESHOLD', 8192),
// TTL window for persisted blobs. Default 168h = 1 week. The resolver
// double-checks the TTL on load even when GC hasn't pruned yet.
spilloverTtlMs: parseInt(getEnv('CLERUM_SPILLOVER_TTL_HOURS', '168')!, 10) * 3600 * 1000,
// Periodic sweep. `0` disables the timer; the lazy boot sweep still runs.
spilloverGcIntervalMs:
parseInt(getEnv('CLERUM_SPILLOVER_GC_INTERVAL_MINUTES', '60')!, 10) * 60 * 1000,
// Native tool configuration
nativeTool: {
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: getToolProgressIntervalMs(),
httpAllowlist: (process.env.CLERUM_HTTP_ALLOWLIST || '')
.split(',')
.map(s => s.trim())
.filter(Boolean),
envAllowlist: (process.env.CLERUM_ENV_ALLOWLIST || 'PATH,HOME,USER,SHELL,LANG,TERM')
.split(',')
.map(s => s.trim()),
memoryMaxSize: parseInt(getEnv('CLERUM_MEMORY_MAX_SIZE', '1048576')!, 10),
// Cron×stateless: mirrors the top-level statelessLifecycle flag so the
// native tool registry (which only receives NativeToolConfig) can steer
// the cron_manage stateless notice.
statelessLifecycle: getEnvBool('CLERUM_STATELESS_LIFECYCLE', false),
attachmentTextReadMaxBytes,
},
// Attachment delivery
enableResponseAttachments: getEnvBool('CLERUM_ENABLE_RESPONSE_ATTACHMENTS', true),
attachmentMaxCount: parseInt(getEnv('CLERUM_ATTACHMENT_MAX_COUNT', '3')!, 10),
attachmentMaxBytes: parseInt(getEnv('CLERUM_ATTACHMENT_MAX_BYTES', '52428800')!, 10),
attachmentFileMaxBytes,
attachmentTextReadMaxBytes,
fileReferenceMaxCount: FILE_REFERENCE_MAX_COUNT,
activityBufferSize: parseInt(getEnv('MCP_HOST_ACTIVITY_BUFFER_SIZE', '1000')!, 10),
activityMaxEventBytes: parseInt(getEnv('MCP_HOST_ACTIVITY_MAX_EVENT_BYTES', '2048')!, 10),
// Memory (workspace) — CLERUM_MEMORY_ENABLED, CLERUM_MEMORY_WORKSPACE_PATH.
memory: {
enabled: getEnvBool('CLERUM_MEMORY_ENABLED', false),
workspacePath: getEnv('CLERUM_MEMORY_WORKSPACE_PATH', devMode ? './workspace' : '/workspace'),
},
// Token budgets (P1)
budgetsEnabled: getEnvBool('CLERUM_BUDGETS_ENABLED', false),
// Governed tracing
governedTracingEnabled: getEnvBool('GOVERNED_TRACING_ENABLED', true),
approvalPromptHistoryEnabled: process.env.TRACING_APPROVAL_PROMPT_HISTORY_ENABLED === 'true',
approvalPromptHistoryMaxBytes: parseApprovalPromptHistoryMaxBytes(
getEnv('TRACING_APPROVAL_PROMPT_HISTORY_MAX_BYTES', '16384')!
),
// Canonical runtime mode. Keep the boolean derived from the discriminant so
// downstream code cannot observe an impossible sdk-only+workflow pairing.
runtimeKind: configuredRuntimeKind,
workflowEnabled: configuredRuntimeKind === 'workflow',
workflowRecipeName: getEnv('CLERUM_WORKFLOW_RECIPE', '')!,
userApprovalRequestRecipeName: getEnv('CLERUM_WORKFLOW_APPROVAL_RECIPE', '')!,
userApprovalRequestRecipeNamespace: getEnv(
'CLERUM_WORKFLOW_APPROVAL_RECIPE_NAMESPACE',
'mcp-host'
)!,
// Auth configuration
enableAuth: getEnvBool('CLERUM_ENABLE_AUTH', true),
authJwtPublicKey: (getEnv('CLERUM_AUTH_JWT_PUBLIC_KEY', '') || '').replace(/\\n/g, '\n'),
authJwtIssuer: getEnv('CLERUM_AUTH_JWT_ISSUER', 'control-api')!,
// Audience must be "rpc-proxy"; control-api stamps that value onto every
// issued RPC token.
authJwtAudience: getEnv('CLERUM_AUTH_JWT_AUDIENCE', 'rpc-proxy')!,
// Verifies workflow-mode tokens (iss: clerum-wrc); separate signer from authJwtPublicKey.
wrcPublicKey: (getEnv('WRC_PUBLIC_KEY_PEM', '') || '').replace(/\\n/g, '\n'),
// mcpHost runtime JWTs for workflow approval gating
mcpHostRuntimeAccessToken: getEnv('MCP_HOST_RUNTIME_ACCESS_TOKEN', ''),
mcpHostRuntimeRefreshToken: getEnv('MCP_HOST_RUNTIME_REFRESH_TOKEN', ''),
mcpHostGatewayUrl: getEnv('MCP_HOST_GATEWAY_URL', ''),
mcpHostWorkflowControlToken: getEnv('MCP_HOST_WORKFLOW_CONTROL_TOKEN', ''),
mcpHostWorkflowControlTokenFile: getEnv('MCP_HOST_WORKFLOW_CONTROL_TOKEN_FILE', ''),
// Plugin Workload SDK (plan §3.5 config table)
pluginWorkloadSdkEnabled: getEnvBool('PLUGIN_WORKLOAD_SDK_ENABLED', false),
pluginWorkloadSdkCapabilities: parsePluginWorkloadSdkCapabilities(
getEnv('PLUGIN_WORKLOAD_SDK_CAPABILITIES', '')
),
// Workflow is the backwards-compatible SDK mode for workflow/standalone
// processes; WRC explicitly sets sdk-only on the stepless adapter.
pluginWorkloadSdkRuntimeMode: configuredRuntimeKind === 'sdk-only' ? 'sdk-only' : 'workflow',
pluginWorkloadSdkPort: parseInt(getEnv('MCP_HOST_PLUGIN_SDK_PORT', '8099')!, 10),
podNamespace: getEnv('MCP_HOST_POD_NAMESPACE', '')!,
pluginWorkloadSdkGatewayUrl: getEnv('CONTROL_API_GATEWAY_URL', ''),
pluginWorkloadSdkCredentialBrokerUrl: getEnv('CLERUM_WRC_URL', '') ?? '',
pluginWorkloadSdkWorkloadToken: getEnv('PLUGIN_WORKLOAD_SDK_WORKLOAD_TOKEN', ''),
pluginWorkloadSdkBoundCallerRef: getEnv('PLUGIN_WORKLOAD_SDK_BOUND_CALLER_REF', ''),
pluginWorkloadSdkWorkloadTokensDir: getEnv('PLUGIN_WORKLOAD_SDK_WORKLOAD_TOKENS_DIR', ''),
pluginWorkloadSdkPromptTimeoutSeconds: parseInt(
getEnv('PLUGIN_WORKLOAD_SDK_PROMPT_TIMEOUT_SECONDS', '120')!,
10
),
pluginWorkloadSdkMaxConnections: parseInt(
getEnv('PLUGIN_WORKLOAD_SDK_MAX_CONNECTIONS', '100')!,
10
),
pluginWorkloadSdkMaxConnectionsPerWorkload: parseInt(
getEnv('PLUGIN_WORKLOAD_SDK_MAX_CONNECTIONS_PER_WORKLOAD', '10')!,
10
),
pluginWorkloadSdkMaxRpmPerWorkload: parseInt(
getEnv('PLUGIN_WORKLOAD_SDK_MAX_RPM_PER_WORKLOAD', '100')!,
10
),
pluginWorkloadSdkMaxLlmResponseBytes: parseInt(
getEnv('PLUGIN_WORKLOAD_SDK_MAX_LLM_RESPONSE_BYTES', String(1024 * 1024))!,
10
),
// Personalization — CLERUM_PERSONALIZATION_ENABLED, CLERUM_IDENTITY_SEED (JSON).
personalization: (() => {
const enabled = getEnvBool('CLERUM_PERSONALIZATION_ENABLED', false)
const seedJson = getEnv('CLERUM_IDENTITY_SEED')
let seed: Omit<PersonalizationConfig, 'enabled'> = {}
if (seedJson) {
try {
seed = JSON.parse(seedJson) as Omit<PersonalizationConfig, 'enabled'>
} catch {
logger.error({ component: 'Config' }, 'Failed to parse identity seed configuration')
}
}
return { enabled, ...seed }
})(),
// Eager catalog-bootstrap probe policy (fail-fast validated at load).
mcpCatalogBootstrap: buildMcpCatalogBootstrapConfig(),
}