Skip to content

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

TypeScript

fix(mcp-host): count messages against the contract bound in compaction pressure (#731)

Alfredo Lopez5483b20ddddf
diff --git a/docs/architecture/codex-subscription-transport-contract.md b/docs/architecture/codex-subscription-transport-contract.md
index 45a9d3dc3..720e2ec80 100644
--- a/docs/architecture/codex-subscription-transport-contract.md
+++ b/docs/architecture/codex-subscription-transport-contract.md
@@ -263,7 +263,15 @@ Stable codes: `insufficient_scope`, `no_grant`, `model_not_allowed`,
| `messages exceed <maxMessages>` | message count |
| `messages[i].toolCalls exceed <maxToolCalls>` | tool calls on one message |
- Compaction is the remedy for all four. The element bound is named distinctly
+ All four mean the conversation is too long, but compaction does not reach
+ them equally. The Host's context manager counts the serialized bytes and,
+ for this provider, the message count against the contract's `maxMessages`,
+ so it compacts before either bound. A single turn holding more than
+ `maxMessages` messages stays unshrinkable, because the cut never lands
+ inside a turn. `maxToolCalls` also bounds every response, so only history
+ produced by another provider can carry an over-long `toolCalls` array.
+
+ The element bound is named distinctly
from the byte cap so that a user report can tell which guard fired, not
because it is fixed differently: a structure with more elements than the byte
cap cannot fit under the byte cap either, so an element-bound refusal is
diff --git a/docs/architecture/grok-subscription-transport-contract.md b/docs/architecture/grok-subscription-transport-contract.md
index 3824703d1..d6239dd2a 100644
--- a/docs/architecture/grok-subscription-transport-contract.md
+++ b/docs/architecture/grok-subscription-transport-contract.md
@@ -279,7 +279,15 @@ Stable codes: `insufficient_scope`, `no_grant`, `model_not_allowed`,
| `messages exceed <maxMessages>` | message count |
| `messages[i].toolCalls exceed <maxToolCalls>` | tool calls on one message |
- Compaction is the remedy for all four. The element bound is named distinctly
+ All four mean the conversation is too long, but compaction does not reach
+ them equally. The Host's context manager counts the serialized bytes and,
+ for this provider, the message count against the contract's `maxMessages`,
+ so it compacts before either bound. A single turn holding more than
+ `maxMessages` messages stays unshrinkable, because the cut never lands
+ inside a turn. `maxToolCalls` also bounds every response, so only history
+ produced by another provider can carry an over-long `toolCalls` array.
+
+ The element bound is named distinctly
from the byte cap so that a user report can tell which guard fired, not
because it is fixed differently: a structure with more elements than the byte
cap cannot fit under the byte cap either, so an element-bound refusal is
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index ca7a156e3..400669dc5 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.385",
+ "version": "0.1.386",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.385",
+ "version": "0.1.386",
"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 715a92333..b27bfac6c 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.385",
+ "version": "0.1.386",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/agent/taskExecutor.ts b/mcp-host/src/agent/taskExecutor.ts
index d4d659da5..1dc576796 100644
--- a/mcp-host/src/agent/taskExecutor.ts
+++ b/mcp-host/src/agent/taskExecutor.ts
@@ -91,7 +91,7 @@ import type { SingleTurnProvider } from '../llm'
import type { ImageInputResolver } from '../llm/imageInput'
import type { PromptCache } from '../llm/promptCache'
import { stampStableHashGauge } from '../llm/promptCacheMetrics'
-import { isLlmProvider } from '../llm/registryCore'
+import { descriptorFor, isLlmProvider } from '../llm/registryCore'
import { logger } from '../logger'
import type { McpManager } from '../mcp'
import { getDisplayName, sanitizeError } from '../progress/intentExtraction.js'
@@ -987,6 +987,18 @@ export class TaskExecutor {
return this.deps.contextWindowTokens ?? appConfig.contextMaxTokens
}
+ /**
+ * #731 — the attempt contract's `maxMessages` for the provider, or
+ * `undefined` when it has none. An unregistered provider type has no
+ * contract, the same case `buildSourceMessageContentParts` guards with
+ * `isLlmProvider`.
+ */
+ private contractMaxMessages(): number | undefined {
+ const providerType = this.deps.llmProvider.getProviderType()
+ if (!isLlmProvider(providerType)) return undefined
+ return descriptorFor(providerType).maxMessages
+ }
+
private getOrCreateTokenCounter(): TokenCounter {
if (!this.tokenCounter) {
this.tokenCounter = createTokenCounter(this.deps.llmProvider, this.deps.modelName, {
@@ -1441,6 +1453,9 @@ export class TaskExecutor {
if (key) this.deps.promptCache!.invalidate(key, 'compact')
}
: undefined,
+ // #731 — the subscription contracts refuse a request on message count
+ // alone; the registry carries that bound from each contract's LIMITS.
+ maxMessages: this.contractMaxMessages(),
}
)
diff --git a/mcp-host/src/core/extensions/__tests__/contextManager.test.ts b/mcp-host/src/core/extensions/__tests__/contextManager.test.ts
index b0d5d6adb..096fc13ee 100644
--- a/mcp-host/src/core/extensions/__tests__/contextManager.test.ts
+++ b/mcp-host/src/core/extensions/__tests__/contextManager.test.ts
@@ -429,8 +429,8 @@ describe('PressureContextManager - archived markdown', () => {
* T-A3 — #731. The deployed decision path for `codex-subscription` and
* `grok-subscription`: a `PressureContextManager` with NO token counter, so
* `computePressure` falls through to `estimateTokens` → `heuristicCount`
- * (`contextManager.ts:484-486`). Both providers map to `FallbackTokenCounter`
- * (`llm/registryCore.ts:203-204`), which is the same word heuristic with a 1.3
+ * (`contextManager.ts:514-516`). Both providers map to `FallbackTokenCounter`
+ * (`llm/registryCore.ts:215-216`), which is the same word heuristic with a 1.3
* bias, so no configuration makes this history compact today.
*
* prom-client metrics are process-global, so this block resets the registry
diff --git a/mcp-host/src/core/extensions/contextManager.ts b/mcp-host/src/core/extensions/contextManager.ts
index f3e7be30b..4a8c6cc10 100644
--- a/mcp-host/src/core/extensions/contextManager.ts
+++ b/mcp-host/src/core/extensions/contextManager.ts
@@ -127,6 +127,15 @@ export interface PressureContextManagerOptions {
* concerns.
*/
onCompactionEffective?: (info: { conversationId: string; tier: CompactionTier }) => void
+
+ /**
+ * #731 — the provider's bound on the number of request messages, taken from
+ * its attempt contract (`LIMITS.maxMessages`). When set, pressure is the
+ * larger of the token ratio and `messages.length / maxMessages`, so a long
+ * history of small turns is compacted before the contract refuses it on
+ * count alone. Omitted for providers without such a bound.
+ */
+ maxMessages?: number
}
type PressureTier = 'passthrough' | 'workspace' | 'summarize' | 'truncate'
@@ -217,6 +226,7 @@ export class PressureContextManager implements ContextManager {
conversationId: string
tier: CompactionTier
}) => void
+ private readonly maxMessages?: number
/**
* T1.1 — Previous structured summary text. Persists across compactions
* within the same task so the next call sends `### Previous Summary` and
@@ -255,6 +265,7 @@ export class PressureContextManager implements ContextManager {
this.prePruneOptions = options.prePruneOptions
this.structuredSummaryEnabled = options.structuredSummaryEnabled ?? false
this.onCompactionEffective = options.onCompactionEffective
+ this.maxMessages = options.maxMessages
}
/**
@@ -476,7 +487,18 @@ export class PressureContextManager implements ContextManager {
}
/**
- * Resolve the pressure ratio according to the dry-run gate. Three branches:
+ * Pressure is the larger of the token ratio and, when the provider's
+ * contract bounds it, the message-count ratio (#731): the contract refuses
+ * `messages.length > maxMessages` whatever the token count.
+ */
+ private async computePressure(messages: ChatMessage[], tools: ToolDefinition[]): Promise<number> {
+ const tokenPressure = await this.computeTokenPressure(messages, tools)
+ if (this.maxMessages === undefined) return tokenPressure
+ return Math.max(tokenPressure, messages.length / this.maxMessages)
+ }
+
+ /**
+ * Resolve the token pressure ratio according to the dry-run gate. Three branches:
* - No counter: legacy heuristic (preserves pre-P.2 behavior bit-for-bit).
* - dryRun=true: compute BOTH numbers; the heuristic decides the tier; the
* delta and any tier mismatch are emitted as metrics for the bake-week.
@@ -485,7 +507,10 @@ export class PressureContextManager implements ContextManager {
* Every branch counts `tools` with the messages: both travel in the request
* the provider caps (#731).
*/
- private async computePressure(messages: ChatMessage[], tools: ToolDefinition[]): Promise<number> {
+ private async computeTokenPressure(
+ messages: ChatMessage[],
+ tools: ToolDefinition[]
+ ): Promise<number> {
if (!this.tokenCounter) {
return (estimateTokens(messages) + heuristicCountTools(tools)) / this.maxTokens
}
diff --git a/mcp-host/src/llm/__tests__/codexSubscription.test.ts b/mcp-host/src/llm/__tests__/codexSubscription.test.ts
index 5ed6e8131..add9efc94 100644
--- a/mcp-host/src/llm/__tests__/codexSubscription.test.ts
+++ b/mcp-host/src/llm/__tests__/codexSubscription.test.ts
@@ -164,7 +164,7 @@ describe('CodexSubscriptionProvider', () => {
const provider = new CodexSubscriptionProvider('gpt-5.3-codex', wired as never)
// A single tool result over the byte cap. The message count is 4, far below
// `maxMessages`, so the refusal can only come from the canonical-hash path
- // at `codexSubscription.ts:331-344` - the one that measures real bytes.
+ // at `codexSubscription.ts:337-350` - the one that measures real bytes.
const oversized = [
{ role: 'system' as const, content: 'you are a helpful assistant' },
{ role: 'user' as const, content: 'list every contact' },
@@ -355,7 +355,7 @@ describe('CodexSubscriptionProvider', () => {
// any of the three patterns, so it only fails under a broadening wide
// enough to swallow an unrelated field - the case T-C4 cannot see.
// `maxOutputTokens` reaches the contract from the caller unclamped
- // (`codexSubscription.ts:259-261` -> `:444`), so this is a refusal a caller
+ // (`codexSubscription.ts:265-267` -> `:450`), so this is a refusal a caller
// can actually provoke, not a synthetic one.
const history = [{ role: 'user' as const, content: 'summarize' }]
diff --git a/mcp-host/src/llm/__tests__/grokSubscription.test.ts b/mcp-host/src/llm/__tests__/grokSubscription.test.ts
index fa61dcab3..b23f7b289 100644
--- a/mcp-host/src/llm/__tests__/grokSubscription.test.ts
+++ b/mcp-host/src/llm/__tests__/grokSubscription.test.ts
@@ -356,7 +356,7 @@ describe('GrokSubscriptionProvider', () => {
const provider = new GrokSubscriptionProvider('grok-4.6', wired as never)
// The Grok mirror of T-C. The guard above refuses on message count; this
// history is 4 messages, so the refusal can only come from the
- // canonical-hash path at `grokSubscription.ts:351-366` - the one that
+ // canonical-hash path at `grokSubscription.ts:357-372` - the one that
// measures real bytes. #728 classified the message count correctly and left
// this path reporting `invalid_request`, which is what reached the user as
// a retryable "Connection Error".
@@ -507,7 +507,7 @@ describe('GrokSubscriptionProvider', () => {
// shares no prefix with any of the three regexes, so it is the distant miss:
// it survives a narrow widening and fails only under one broad enough to
// swallow an unrelated field. `max_tokens` reaches the contract from the
- // caller unclamped (`grokSubscription.ts:281` -> `:465`), so this is a
+ // caller unclamped (`grokSubscription.ts:287` -> `:471`), so this is a
// refusal a caller can provoke, not a synthetic one.
const history = [{ role: 'user' as const, content: 'summarize' }]
diff --git a/mcp-host/src/llm/codexSubscription.ts b/mcp-host/src/llm/codexSubscription.ts
index 5873cd623..1d52c4cdb 100644
--- a/mcp-host/src/llm/codexSubscription.ts
+++ b/mcp-host/src/llm/codexSubscription.ts
@@ -39,8 +39,14 @@ export type CodexAttemptContext = {
* `fail('limit', …)` guards eight checks, and only these are about volume: the
* real byte bound (`index.cjs:391`), the element bound that proxies it
* (`:193`), `maxMessages` (`:239`) and `messages[i].toolCalls` (`:266`).
- * Compaction is the remedy for all four, which is exactly what
+ * All four are "this conversation is too long", which is exactly what
* `ContextLengthExceeded` — "Conversation Too Long" — promises the user.
+ * Compaction reaches them unevenly. The context manager counts bytes and,
+ * through the registry's `maxMessages`, the message count, so it compacts
+ * before either bound; a single turn holding more than `maxMessages`
+ * messages stays unshrinkable, because the cut never lands inside a turn.
+ * `maxToolCalls` also bounds every response, so only history produced by
+ * another provider can carry an over-long `toolCalls` array.
*
* The other four are not. Nesting depth (`:180`, `:215`),
* `generation.maxOutputTokens` and `deadlineMs` out of range are malformed or
diff --git a/mcp-host/src/llm/grokSubscription.ts b/mcp-host/src/llm/grokSubscription.ts
index 5d6791d97..84749c958 100644
--- a/mcp-host/src/llm/grokSubscription.ts
+++ b/mcp-host/src/llm/grokSubscription.ts
@@ -36,7 +36,7 @@ export type GrokAttemptContext = {
/**
* The contract `limit` refusals that mean "this turn carries too much".
*
- * The Grok twin of `codexSubscription.ts:62-70`. The two are deliberate
+ * The Grok twin of `codexSubscription.ts:68-76`. The two are deliberate
* duplicates, not an accident: `grok-provider-attempt-contract/index.cjs:6`
* states that this package does not import the Codex contract's LIMITS, and a
* shared predicate would either recreate that coupling or pin prose rather than
@@ -47,8 +47,14 @@ export type GrokAttemptContext = {
* `fail('limit', …)` guards eight checks here too, and only these are about
* volume: the real byte bound (`index.cjs:414`), the element bound that proxies
* it (`:214`), `maxMessages` (`:260`) and `messages[i].toolCalls` (`:289`).
- * Compaction is the remedy for all four, which is exactly what
+ * All four are "this conversation is too long", which is exactly what
* `ContextLengthExceeded` — "Conversation Too Long" — promises the user.
+ * Compaction reaches them unevenly. The context manager counts bytes and,
+ * through the registry's `maxMessages`, the message count, so it compacts
+ * before either bound; a single turn holding more than `maxMessages`
+ * messages stays unshrinkable, because the cut never lands inside a turn.
+ * `maxToolCalls` also bounds every response, so only history produced by
+ * another provider can carry an over-long `toolCalls` array.
*
* The other four are not. Nesting depth (`:199`, `:236`),
* `generation.maxOutputTokens` (`:376`) and `deadlineMs` (`:445`) out of range
diff --git a/mcp-host/src/llm/registryCore.ts b/mcp-host/src/llm/registryCore.ts
index 1dc3972a6..e986a56e0 100644
--- a/mcp-host/src/llm/registryCore.ts
+++ b/mcp-host/src/llm/registryCore.ts
@@ -17,6 +17,10 @@
* provider is a single entry here; a divergent provider (e.g. Claude) is one
* entry here plus its own class wired in `./registry`.
*/
+// The attempt contracts require only `node:crypto`, so reading their LIMITS
+// keeps this module a data-only leaf.
+import { LIMITS as GROK_CONTRACT_LIMITS } from '@clerum/grok-provider-attempt-contract'
+import { LIMITS as CODEX_CONTRACT_LIMITS } from '@clerum/llm-provider-attempt-contract'
import {
type CredentialSlot,
type LlmProviderId,
@@ -78,6 +82,12 @@ export interface CoreProviderDescriptor {
* does not use this hint (Claude).
*/
tokenizer: 'openai' | 'fallback' | 'native'
+ /**
+ * The attempt contract's bound on request messages (`LIMITS.maxMessages`),
+ * which the context manager counts as pressure (#731). Absent for providers
+ * without an attempt contract.
+ */
+ maxMessages?: number
}
/** The `LlmProvider` union is the shared canonical set (data-only leaf). */
@@ -94,6 +104,7 @@ interface RuntimeProviderFields {
/** Base URL for OpenAI-compatible providers (zai, bailian). */
baseURL?: string
tokenizer: CoreProviderDescriptor['tokenizer']
+ maxMessages?: number
}
const RUNTIME_FIELDS: Record<LlmProvider, RuntimeProviderFields> = {
@@ -199,9 +210,10 @@ const RUNTIME_FIELDS: Record<LlmProvider, RuntimeProviderFields> = {
// data-driven baseURL arm. Tokenizer 'openai' (it serves OpenAI models) and
// defaultModel is the Azure DEPLOYMENT name the operator expects by default.
azure: { defaultModel: 'gpt-4.1', tokenizer: 'openai' },
- // Broker: explicit model required later; no Secret slot and no default.
- 'codex-subscription': { tokenizer: 'fallback' },
- 'grok-subscription': { tokenizer: 'fallback' },
+ // Broker: explicit model required later; no Secret slot and no default. The
+ // message bound is read from each contract, never written as a literal.
+ 'codex-subscription': { tokenizer: 'fallback', maxMessages: CODEX_CONTRACT_LIMITS.maxMessages },
+ 'grok-subscription': { tokenizer: 'fallback', maxMessages: GROK_CONTRACT_LIMITS.maxMessages },
}
// Order = dev auto-detection priority (first present key wins), inherited from