Skip to content

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

TypeScript

docs(#731): correct the claims and references the review found wrong

Alfredo Lopezb6dfad9e37e2
diff --git a/docs/architecture/codex-subscription-transport-contract.md b/docs/architecture/codex-subscription-transport-contract.md
index 939952a4e..45a9d3dc3 100644
--- a/docs/architecture/codex-subscription-transport-contract.md
+++ b/docs/architecture/codex-subscription-transport-contract.md
@@ -256,16 +256,20 @@ Stable codes: `insufficient_scope`, `no_grant`, `model_not_allowed`,
the refusal message because `parse*CompletionRequestV1` returns
`{ ok, code, message }` and nothing else:
- | Refusal message | Guard |
- | --------------------------------------------------- | ---------------------------- |
- | `request exceeds maxRequestBodyBytes` | serialized UTF-8 byte cap |
- | `request exceeds maxRequestBodyBytes element bound` | element count in `checkStructure` |
- | `messages exceed <maxMessages>` | message count |
- | `messages[i].toolCalls exceed <maxToolCalls>` | tool calls on one message |
-
- The element bound is named distinctly from the byte cap because the two have
- different remedies and a user report of the shared wording could not tell
- them apart. The contract's remaining `limit` refusals — nesting depth,
+ | Refusal message | Guard |
+ | --------------------------------------------------- | --------------------------------- |
+ | `request exceeds maxRequestBodyBytes` | serialized UTF-8 byte cap |
+ | `request exceeds maxRequestBodyBytes element bound` | element count in `checkStructure` |
+ | `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
+ 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
+ always also a byte-bound one.
+
+ The contract's remaining `limit` refusals — nesting depth,
`generation.maxOutputTokens` and `deadlineMs` out of range — stay
`invalid_request`: a shorter conversation fixes none of them, and labelling
them a context-length failure would invite a compaction loop that cannot
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index f376de756..c768862a2 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.374",
+ "version": "0.1.375",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.374",
+ "version": "0.1.375",
"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 01ea2fa1e..9021b03f0 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.374",
+ "version": "0.1.375",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/__tests__/fixtures/minifiedMcpResult.ts b/mcp-host/src/__tests__/fixtures/minifiedMcpResult.ts
index 610136de7..862d2f0d7 100644
--- a/mcp-host/src/__tests__/fixtures/minifiedMcpResult.ts
+++ b/mcp-host/src/__tests__/fixtures/minifiedMcpResult.ts
@@ -6,7 +6,7 @@
* The payload shape is the point, not the size. A word count collapses dense
* minified JSON into a handful of "words" because there is no whitespace to
* split on, which is the defect `heuristicCount` carries and
- * `heuristicCountTools` already documents (`core/tokenizer/heuristic.ts:24-38`).
+ * `heuristicCountTools` already documents in `core/tokenizer/heuristic.ts`.
* A prose fixture of the same byte size does NOT reproduce it: prose carries a
* space every few characters, so its word count tracks its byte count and the
* gauge reads it correctly.
diff --git a/mcp-host/src/core/conversation/compaction.ts b/mcp-host/src/core/conversation/compaction.ts
index c4abda8f0..44f4e10f8 100644
--- a/mcp-host/src/core/conversation/compaction.ts
+++ b/mcp-host/src/core/conversation/compaction.ts
@@ -233,9 +233,12 @@ export function compactConversation(
counter?: TokenCounter,
prePruneOpts?: { enabled: boolean; options?: PrePruneOptions }
): ChatMessage[] {
- // T1.2: optional pre-prune BEFORE the threshold check. Disabled by default
- // (caller passes the env-gated flag). Pre-prune is a no-op if it doesn't
- // mutate anything, so cheap to leave in the call chain.
+ // T1.2: optional pre-prune BEFORE the threshold check. The caller passes the
+ // env-gated flag, and `CLERUM_COMPACTION_PRE_PRUNE` now defaults to `true`
+ // (#731), so this runs on every call - including the ones that return early
+ // below because the conversation is under the threshold. Pre-prune is a
+ // no-op if it doesn't mutate anything, so cheap to leave in the call chain,
+ // but it does mean `working` can differ from `messages` on that early return.
let working = messages
if (prePruneOpts?.enabled) {
const result = prePrune(messages, prePruneOpts.options)
diff --git a/mcp-host/src/core/extensions/__tests__/contextManager.test.ts b/mcp-host/src/core/extensions/__tests__/contextManager.test.ts
index c8009f2b3..a2fabe4c1 100644
--- a/mcp-host/src/core/extensions/__tests__/contextManager.test.ts
+++ b/mcp-host/src/core/extensions/__tests__/contextManager.test.ts
@@ -429,7 +429,7 @@ 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:469-471`). Both providers map to `FallbackTokenCounter`
+ * (`contextManager.ts:484-486`). Both providers map to `FallbackTokenCounter`
* (`llm/registryCore.ts:203-204`), which is the same word heuristic with a 1.3
* bias, so no configuration makes this history compact today.
*
diff --git a/mcp-host/src/llm/__tests__/contextOverrunJourney.test.ts b/mcp-host/src/llm/__tests__/contextOverrunJourney.test.ts
index 694c6dda4..c1442ad3a 100644
--- a/mcp-host/src/llm/__tests__/contextOverrunJourney.test.ts
+++ b/mcp-host/src/llm/__tests__/contextOverrunJourney.test.ts
@@ -33,7 +33,7 @@ const requestHash = 'a'.repeat(64)
/**
* The provider's dependencies, with `authorize` and `stream` as spies. Same
- * shape as the `deps()` helper in `codexSubscription.test.ts:21-47`; replicated
+ * shape as the `deps()` helper in `codexSubscription.test.ts`; replicated
* here rather than exported from that file so neither test file constrains the
* other's fixtures.
*/
diff --git a/mcp-host/src/llm/codexSubscription.ts b/mcp-host/src/llm/codexSubscription.ts
index c22a8a713..5873cd623 100644
--- a/mcp-host/src/llm/codexSubscription.ts
+++ b/mcp-host/src/llm/codexSubscription.ts
@@ -37,12 +37,12 @@ export type CodexAttemptContext = {
* The contract `limit` refusals that mean "this turn carries too much".
*
* `fail('limit', …)` guards eight checks, and only these are about volume: the
- * real byte bound (`index.cjs:383`), the element bound that proxies it
- * (`:185`), `maxMessages` (`:231`) and `messages[i].toolCalls` (`:258`).
+ * 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
* `ContextLengthExceeded` — "Conversation Too Long" — promises the user.
*
- * The other four are not. Nesting depth (`:180`, `:207`),
+ * The other four are not. Nesting depth (`:180`, `:215`),
* `generation.maxOutputTokens` and `deadlineMs` out of range are malformed or
* out-of-range parameters, and a shorter conversation fixes none of them;
* labelling them a context-length failure would send the user into a
@@ -53,6 +53,11 @@ export type CodexAttemptContext = {
* so the message is the only discriminator available at this boundary (#731).
* The byte pattern is a prefix so it keeps matching once the element bound gets
* its own distinct wording.
+ *
+ * `messages exceed` is defence in depth rather than a reachable branch: the
+ * guard below raises that exact message with this same classification before
+ * `hashCanonicalCodexRequest` runs, so the contract's own copy of it only
+ * arrives here if that guard is ever removed.
*/
const CONTEXT_LENGTH_REFUSALS = [
/^request exceeds maxRequestBodyBytes/,
diff --git a/packages/grok-provider-attempt-contract/index.cjs b/packages/grok-provider-attempt-contract/index.cjs
index 10be620d1..8aef8bef5 100644
--- a/packages/grok-provider-attempt-contract/index.cjs
+++ b/packages/grok-provider-attempt-contract/index.cjs
@@ -194,11 +194,11 @@ function checkStructure(value, maxDepth) {
// Named distinctly from the byte measurement below, which refuses with
// the bare `request exceeds maxRequestBodyBytes`. Both are `limit`
// failures and `fail()` carries no field beyond code and message, so the
- // wording is the only thing that tells a user report which guard fired -
- // and the two have different remedies (#731). The bound is reused rather
- // than given a constant of its own because an element is cheaper than a
- // byte to serialize: a structure with more elements than the byte cap
- // cannot fit under it.
+ // wording is the only thing that tells a user report which guard fired.
+ // The remedy is the same for both - compaction - and the bound is reused
+ // rather than given a constant of its own, for the same reason: an
+ // element is cheaper than a byte to serialize, so a structure with more
+ // elements than the byte cap cannot fit under it either (#731).
return fail('limit', 'request exceeds maxRequestBodyBytes element bound')
}
for (const child of children) {
diff --git a/packages/grok-provider-attempt-contract/index.test.cjs b/packages/grok-provider-attempt-contract/index.test.cjs
index 1a13b3a0b..b04bbca74 100644
--- a/packages/grok-provider-attempt-contract/index.test.cjs
+++ b/packages/grok-provider-attempt-contract/index.test.cjs
@@ -302,12 +302,15 @@ test('T-E2 the element bound reports itself distinctly from the byte bound', ()
// Same defect as the Codex contract's: the element count inside
// `checkStructure` and the real byte measurement refuse with the identical
// sentence, so a user report of `request exceeds maxRequestBodyBytes` cannot
- // name the guard that fired (#731).
+ // name the guard that fired. Compaction is the remedy either way; the
+ // distinct wording buys diagnosis, not a different fix (#731).
//
- // `checkStructure` runs before `JSON.stringify`, so this guard fires first
- // and `maxMessages` is never reached. The payload below is far past the
- // element cap while its serialized size is a fraction of the byte cap, which
- // is what makes the two guards distinguishable at all.
+ // What makes the two guards separable here is ORDER, not size:
+ // `checkStructure` runs before `JSON.stringify`, so the element count is
+ // refused first. The payload below is also ~3x the byte cap once serialized
+ // — by construction it has to be, since more elements than the byte cap
+ // cannot encode under it — so without that ordering the byte bound would
+ // claim it and this test would be pinning the wrong guard.
const refused = contract.parseGrokCompletionRequestV1({
...BASE,
messages: new Array(contract.LIMITS.maxRequestBodyBytes + 1).fill({}),
diff --git a/packages/llm-provider-attempt-contract/index.cjs b/packages/llm-provider-attempt-contract/index.cjs
index 2db5ba59f..6fdf268e4 100644
--- a/packages/llm-provider-attempt-contract/index.cjs
+++ b/packages/llm-provider-attempt-contract/index.cjs
@@ -185,11 +185,11 @@ function checkStructure(value, maxDepth) {
// Named distinctly from the byte measurement below, which refuses with
// the bare `request exceeds maxRequestBodyBytes`. Both are `limit`
// failures and `fail()` carries no field beyond code and message, so the
- // wording is the only thing that tells a user report which guard fired -
- // and the two have different remedies (#731). The bound is reused rather
- // than given a constant of its own because an element is cheaper than a
- // byte to serialize: a structure with more elements than the byte cap
- // cannot fit under it.
+ // wording is the only thing that tells a user report which guard fired.
+ // The remedy is the same for both - compaction - and the bound is reused
+ // rather than given a constant of its own, for the same reason: an
+ // element is cheaper than a byte to serialize, so a structure with more
+ // elements than the byte cap cannot fit under it either (#731).
return fail('limit', 'request exceeds maxRequestBodyBytes element bound')
}
for (const child of children) {
diff --git a/packages/llm-provider-attempt-contract/index.test.cjs b/packages/llm-provider-attempt-contract/index.test.cjs
index 9818c741d..9aa16c110 100644
--- a/packages/llm-provider-attempt-contract/index.test.cjs
+++ b/packages/llm-provider-attempt-contract/index.test.cjs
@@ -318,14 +318,15 @@ test('T-E2 the element bound reports itself distinctly from the byte bound', ()
// Two different guards refuse with the identical sentence today: the element
// count inside `checkStructure` and the real byte measurement that the two
// tests above pin. A user reporting `request exceeds maxRequestBodyBytes`
- // therefore cannot say which one fired, and the remedies differ — a shorter
- // conversation for the byte cap, a less fragmented structure for this one
- // (#731).
+ // therefore cannot say which one fired. Compaction is the remedy either way;
+ // the distinct wording buys diagnosis, not a different fix (#731).
//
- // `checkStructure` runs before `JSON.stringify`, so this guard fires first
- // and `maxMessages` is never reached. The payload below is far past the
- // element cap while its serialized size is a fraction of the byte cap, which
- // is what makes the two guards distinguishable at all.
+ // What makes the two guards separable here is ORDER, not size:
+ // `checkStructure` runs before `JSON.stringify`, so the element count is
+ // refused first. The payload below is also ~3x the byte cap once serialized
+ // — by construction it has to be, since more elements than the byte cap
+ // cannot encode under it — so without that ordering the byte bound would
+ // claim it and this test would be pinning the wrong guard.
const refused = contract.parseCodexCompletionRequestV1({
...BASE,
messages: new Array(contract.LIMITS.maxRequestBodyBytes + 1).fill({}),