Skip to content

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

TypeScript

fix(guardrails): point-aware hook response caps; stop discarding rewrites (§8.1)

Andy Paviae4a266a0902b
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index b57a314ef..1437fd8eb 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.258",
+ "version": "0.1.259",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.258",
+ "version": "0.1.259",
"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 100b6aafb..e0571f565 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.258",
+ "version": "0.1.259",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/core/adapters/hookedLlmPort.ts b/mcp-host/src/core/adapters/hookedLlmPort.ts
index fe3726f5e..11eef70f9 100644
--- a/mcp-host/src/core/adapters/hookedLlmPort.ts
+++ b/mcp-host/src/core/adapters/hookedLlmPort.ts
@@ -266,6 +266,9 @@ export function maybeWrapHookedLlmPort(
const hooks = buildLlmLaneHooks(config?.hookDescriptors, {
getAuthToken: deps.getAuthToken ?? (() => ''),
fetchImpl: deps.fetchImpl,
+ // Per-point response caps from the admin limits block (§5); defaults in the fetcher.
+ maxOutputBytes: config?.limits?.maxHookOutputBytes,
+ maxRewriteBytes: config?.limits?.maxHookRewriteBytes,
})
const hasHooks =
hooks.preCall.length > 0 ||
diff --git a/mcp-host/src/core/guardrails/config.ts b/mcp-host/src/core/guardrails/config.ts
index 7bf1dcf06..1252aeafa 100644
--- a/mcp-host/src/core/guardrails/config.ts
+++ b/mcp-host/src/core/guardrails/config.ts
@@ -32,7 +32,10 @@ export interface GuardrailLimits {
maxRules?: number
maxHooksPerPhase?: number
maxHookTimeoutMs?: number
+ /** Tight cap for non-rewrite hook responses (moderate/post_call/on_error). Default 1 MiB. */
maxHookOutputBytes?: number
+ /** Generous cap for `pre_call` rewrite output — the whole conversation. Default 5 MiB (~1M tokens). */
+ maxHookRewriteBytes?: number
}
/**
diff --git a/mcp-host/src/core/guardrails/hooks/__tests__/hookFetcher.test.ts b/mcp-host/src/core/guardrails/hooks/__tests__/hookFetcher.test.ts
index 71d5c7406..2af11de64 100644
--- a/mcp-host/src/core/guardrails/hooks/__tests__/hookFetcher.test.ts
+++ b/mcp-host/src/core/guardrails/hooks/__tests__/hookFetcher.test.ts
@@ -64,3 +64,44 @@ describe('createHookFetcher transport routing', () => {
expect(res.status).toBe(0)
})
})
+
+describe('point-aware response caps (§8.1)', () => {
+ // ~ (chars+10) byte JSON body, valid so pre_call parses when under its cap.
+ const bigFetch = (chars: number): FetchLike => {
+ const body = JSON.stringify({ pad: 'x'.repeat(chars) })
+ return vi.fn(async () => ({ status: 200, text: async () => body }))
+ }
+ const caps = (fetchImpl: FetchLike) =>
+ createHookFetcher({
+ getAuthToken: () => 't',
+ fetchImpl,
+ maxOutputBytes: 100,
+ maxRewriteBytes: 1000,
+ })
+
+ it('pre_call: a large rewrite UNDER the generous rewrite cap is applied (not oversized)', async () => {
+ const f = caps(bigFetch(500))
+ const out = await f({ point: 'pre_call', descriptor: base, body: {} })
+ expect(out.unavailable).toBe(false)
+ expect(out.oversized).toBeFalsy()
+ expect(out.body).toBeDefined()
+ })
+
+ it('moderate: the SAME body exceeds the tight response cap → oversized + unavailable', async () => {
+ const f = caps(bigFetch(500))
+ const out = await f({
+ point: 'moderate',
+ descriptor: { ...base, lifecyclePoints: ['moderate'] },
+ body: {},
+ })
+ expect(out.unavailable).toBe(true)
+ expect(out.oversized).toBe(true)
+ })
+
+ it('pre_call: over EVEN the rewrite cap → oversized + unavailable', async () => {
+ const f = caps(bigFetch(2000))
+ const out = await f({ point: 'pre_call', descriptor: base, body: {} })
+ expect(out.unavailable).toBe(true)
+ expect(out.oversized).toBe(true)
+ })
+})
diff --git a/mcp-host/src/core/guardrails/hooks/__tests__/remoteLlmHook.test.ts b/mcp-host/src/core/guardrails/hooks/__tests__/remoteLlmHook.test.ts
index 1cf40e8f0..43ff2a4f3 100644
--- a/mcp-host/src/core/guardrails/hooks/__tests__/remoteLlmHook.test.ts
+++ b/mcp-host/src/core/guardrails/hooks/__tests__/remoteLlmHook.test.ts
@@ -412,6 +412,20 @@ describe('circuit breaker (§8.6)', () => {
expect(cf.calls()).toBe(6) // never short-circuited
})
+ it('oversized responses do NOT trip the breaker (response-too-big ≠ hook-down)', async () => {
+ const reg = new HookBreakerRegistry()
+ const oversized: HookFetcher = async () => ({
+ status: 200,
+ body: undefined,
+ unavailable: true,
+ oversized: true,
+ })
+ const h = new RemoteLlmHook(advisory(), oversized, reg, () => 0)
+ for (let i = 0; i < 10; i++) await h.moderate(req()) // far past failureThreshold(3)
+ // Breaker never opens → a small payload that fits would still be dialed.
+ expect(reg.isOpen('http://svc/', 0)).toBe(false)
+ })
+
it('strict mode never trips (always dials)', async () => {
const reg = new HookBreakerRegistry()
const cf = countingFetcher(() => unavailable)
diff --git a/mcp-host/src/core/guardrails/hooks/hookFetcher.ts b/mcp-host/src/core/guardrails/hooks/hookFetcher.ts
index 0f1bc0801..c63b734a5 100644
--- a/mcp-host/src/core/guardrails/hooks/hookFetcher.ts
+++ b/mcp-host/src/core/guardrails/hooks/hookFetcher.ts
@@ -28,7 +28,10 @@ export type FetchLike = (
export interface HookFetcherDeps {
getAuthToken: () => string
timeoutMs?: number
+ /** Tight cap for non-rewrite responses (moderate/post_call/on_error/tool). Default 1 MiB. */
maxOutputBytes?: number
+ /** Generous cap for `pre_call` rewrite output (the whole conversation). Default 5 MiB (~1M tokens). */
+ maxRewriteBytes?: number
/** In-cluster transport. Defaults to the global `fetch`. */
fetchImpl?: FetchLike
/** External (remote) transport. Defaults to the SSRF-guarded impl. Injectable for tests. */
@@ -119,14 +122,24 @@ function makeInClusterFetch(maxBytes: number): FetchLike {
export function createHookFetcher(deps: HookFetcherDeps): HookFetcher {
const timeoutMs = deps.timeoutMs ?? 5000
- const maxOutputBytes = deps.maxOutputBytes ?? 65536
- const inClusterFetch: FetchLike = deps.fetchImpl ?? makeInClusterFetch(maxOutputBytes)
+ // Point-aware response caps (§8.1). A `pre_call` `may_rewrite` output IS the whole
+ // (possibly compressed) conversation — legitimately large — whereas a `moderate`
+ // verdict, a `post_call` redaction, or an `on_error` recovery is small. A single
+ // tight cap for all silently discards rewrites (they blow past 64 KiB) and no-ops
+ // the hook. So: a generous cap for pre_call, a tight cap for everything else.
+ const rewriteCap = deps.maxRewriteBytes ?? 5 * 1024 * 1024 // pre_call: ~1M tokens
+ const responseCap = deps.maxOutputBytes ?? 1 * 1024 * 1024 // moderate / post_call / on_error / tool
+ // The streaming transports enforce only the LARGER ceiling — purely for memory
+ // safety (OOM/flood, §8.6). The per-point APPLICATION cap is checked after parse.
+ const memoryCeiling = Math.max(rewriteCap, responseCap)
+ const inClusterFetch: FetchLike = deps.fetchImpl ?? makeInClusterFetch(memoryCeiling)
const externalFetch: FetchLike =
- deps.externalFetchImpl ?? makeSsrfGuardedFetch(timeoutMs, maxOutputBytes)
+ deps.externalFetchImpl ?? makeSsrfGuardedFetch(timeoutMs, memoryCeiling)
return async ({ point, descriptor, body }) => {
const url = buildHookUrl(descriptor.endpoint, descriptor.path, point)
const doFetch = descriptor.external ? externalFetch : inClusterFetch
+ const applyCap = point === 'pre_call' ? rewriteCap : responseCap
try {
const res = await doFetch(url, {
method: 'POST',
@@ -138,8 +151,15 @@ export function createHookFetcher(deps: HookFetcherDeps): HookFetcher {
signal: AbortSignal.timeout(timeoutMs),
})
const text = await res.text()
- if (text.length > maxOutputBytes) {
- return { status: res.status, body: undefined, unavailable: true } // oversized → unavailable
+ if (text.length > applyCap) {
+ // Over the per-point cap → cannot be applied. NEVER silent (this used to
+ // no-op a rewrite invisibly), and flagged `oversized` so the §8.6 breaker
+ // does NOT count "response too big" as a hook-down failure (§12.4).
+ console.warn(
+ `[Guardrails] hook ${descriptor.id} ${point} response ${text.length}B exceeds the ` +
+ `${point === 'pre_call' ? 'rewrite' : 'response'} cap (${applyCap}B) — discarding as unavailable`
+ )
+ return { status: res.status, body: undefined, unavailable: true, oversized: true }
}
let parsed: unknown = {}
if (text) {
diff --git a/mcp-host/src/core/guardrails/hooks/remoteLlmHook.ts b/mcp-host/src/core/guardrails/hooks/remoteLlmHook.ts
index 0b43c0987..31f07c882 100644
--- a/mcp-host/src/core/guardrails/hooks/remoteLlmHook.ts
+++ b/mcp-host/src/core/guardrails/hooks/remoteLlmHook.ts
@@ -131,7 +131,13 @@ export class RemoteLlmHook {
const res = await this.fetchWithDeadline(args)
if (engaged) {
const policy = this.descriptor.onUnavailable!
- if (res.unavailable) {
+ // "Response too big" (oversized) is NOT a hook-down failure — it must not
+ // trip the breaker (which would then skip small payloads that would fit).
+ // Leave breaker state unchanged for oversized; only a real transport failure
+ // counts, and a reachable response resets it.
+ if (res.oversized) {
+ // no-op on breaker state
+ } else if (res.unavailable) {
const tripped = this.breakers.recordFailure(
this.breakerKey(),
policy.failureThreshold,
diff --git a/mcp-host/src/core/guardrails/hooks/types.ts b/mcp-host/src/core/guardrails/hooks/types.ts
index 8f5e51aa1..704064489 100644
--- a/mcp-host/src/core/guardrails/hooks/types.ts
+++ b/mcp-host/src/core/guardrails/hooks/types.ts
@@ -76,6 +76,12 @@ export interface HookHttpResult {
status: number
body: unknown
unavailable: boolean
+ /**
+ * True when the response was rejected for exceeding the per-point size cap
+ * (§8.1). Still `unavailable` (the response can't be applied), but "response too
+ * big" is NOT a hook-down failure — the §8.6 breaker must not count it.
+ */
+ oversized?: boolean
}
/** Injected transport: POST the redacted body to `{endpoint}{path}/v1/{point}` and return the parsed result. */
diff --git a/mcp-host/src/core/guardrails/llm/llmLaneHooks.ts b/mcp-host/src/core/guardrails/llm/llmLaneHooks.ts
index 1efd80119..cc19163c8 100644
--- a/mcp-host/src/core/guardrails/llm/llmLaneHooks.ts
+++ b/mcp-host/src/core/guardrails/llm/llmLaneHooks.ts
@@ -19,6 +19,9 @@ export interface LlmLaneHookDeps {
getAuthToken: () => string
/** Injected for tests / a future SSRF-guarded remote transport. */
fetchImpl?: FetchLike
+ /** Per-point response caps (spec §5/§8.1). Defaults applied in `createHookFetcher`. */
+ maxOutputBytes?: number
+ maxRewriteBytes?: number
}
export function buildLlmLaneHooks(
@@ -33,7 +36,12 @@ export function buildLlmLaneHooks(
for (const d of ordered) {
const hook = new RemoteLlmHook(
d,
- createHookFetcher({ getAuthToken: deps.getAuthToken, fetchImpl: deps.fetchImpl })
+ createHookFetcher({
+ getAuthToken: deps.getAuthToken,
+ fetchImpl: deps.fetchImpl,
+ maxOutputBytes: deps.maxOutputBytes,
+ maxRewriteBytes: deps.maxRewriteBytes,
+ })
)
if (d.lifecyclePoints.includes('pre_call')) preCall.push(hook)
if (d.lifecyclePoints.includes('moderate')) moderate.push(hook)