Skip to content

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

TypeScript

docs(mcp-host): cite symbols instead of line numbers (#739)

Alfredo Lopez1ad2045ba415
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 26665d124..c3449d463 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.425",
+ "version": "0.1.426",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.425",
+ "version": "0.1.426",
"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 f3d1ea0b0..5142b8e21 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.425",
+ "version": "0.1.426",
"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/extensions/__tests__/contextManager.antiThrash.test.ts b/mcp-host/src/core/extensions/__tests__/contextManager.antiThrash.test.ts
index bccce34be..1d0feef51 100644
--- a/mcp-host/src/core/extensions/__tests__/contextManager.antiThrash.test.ts
+++ b/mcp-host/src/core/extensions/__tests__/contextManager.antiThrash.test.ts
@@ -5,8 +5,11 @@
* plus the §8.3 Test A (defensive pending_approval guard does not mutate the
* compaction counter).
*
- * Fixtures rely on the heuristic token estimator (`heuristicCount`): ceil(chars/4)+4
- * per message (#731; it was floor(words×1.3)+4 before). We build deterministic
+ * Fixtures rely on the heuristic token estimator (`heuristicCount`): per message,
+ * ceil(B/4)+4, where B is the UTF-8 byte length of the content as it serializes
+ * inside JSON (escapes included, quotes excluded), plus ceil(B/4) for each tool
+ * call's JSON arguments (#731; it was floor(words×1.3)+4 before). For the
+ * plain-ASCII fixtures below B equals the character count. We build deterministic
* fixtures rather than mocking the estimator so the assertions exercise the real
* wiring end-to-end.
*/
diff --git a/mcp-host/src/core/extensions/__tests__/contextManager.test.ts b/mcp-host/src/core/extensions/__tests__/contextManager.test.ts
index 7549c9b95..1eb7bb602 100644
--- a/mcp-host/src/core/extensions/__tests__/contextManager.test.ts
+++ b/mcp-host/src/core/extensions/__tests__/contextManager.test.ts
@@ -465,8 +465,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
* `computeTokenPressure` falls through to `estimateTokens` → `heuristicCount`
- * (`contextManager.ts:521-522`). Both providers map to `FallbackTokenCounter`
- * (`llm/registryCore.ts:215-216`), which counts through the same
+ * (via `tierDecisionTokens`). Both providers map to `FallbackTokenCounter`
+ * (their `PROVIDERS` descriptors in `llm/registryCore.ts`), which counts through the same
* `heuristicCount`, so this case covers the counter path as well. The
* heuristic counts escaped UTF-8 bytes / 4, the quantity the contract caps;
* the word count it replaced undercounted minified JSON and left this history
diff --git a/mcp-host/src/core/tokenizer/heuristic.ts b/mcp-host/src/core/tokenizer/heuristic.ts
index 3546cd664..93edeae3f 100644
--- a/mcp-host/src/core/tokenizer/heuristic.ts
+++ b/mcp-host/src/core/tokenizer/heuristic.ts
@@ -23,7 +23,7 @@
*
* This is the count that selects the compaction tier for EVERY provider in the
* default configuration, not only a fallback: `CLERUM_TOKENIZER_DRYRUN`
- * defaults to true (`config.ts:793`), and under dry-run `computePressure`
+ * defaults to true (`tokenizerDryrun` in `config.ts`), and under dry-run `computePressure`
* decides the tier from this heuristic and uses an exact counter only to record
* the delta. It is exact nowhere — it ignores `contentParts` and
* provider-specific framing.
@@ -46,7 +46,7 @@ export function heuristicCount(messages: ChatMessage[]): number {
total += Math.ceil(jsonStringBytes(msg.content ?? '') / 4) + 4
// An assistant message that issues a tool call carries its payload here,
// never in `content`; without this the whole call bills at the framing
- // overhead alone (#731). `openaiTokenCounter.ts:58-62` walks the same field
+ // overhead alone (#731). `OpenAITokenCounter.countSync` walks the same field
// and also encodes each call's `id` and `name`; only the arguments are
// counted here, since they carry the payload.
for (const tc of msg.tool_calls ?? []) {
diff --git a/mcp-host/src/llm/__tests__/codexSubscription.test.ts b/mcp-host/src/llm/__tests__/codexSubscription.test.ts
index 7eb10745e..c7fb920c0 100644
--- a/mcp-host/src/llm/__tests__/codexSubscription.test.ts
+++ b/mcp-host/src/llm/__tests__/codexSubscription.test.ts
@@ -177,7 +177,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:339-352` - the one that measures real bytes.
+ // (`hashCanonicalCodexRequest` in `execute`) - 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' },
@@ -401,8 +401,9 @@ 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:267-270` -> `:452`), so this is a refusal a caller
- // can actually provoke, not a synthetic one.
+ // (`completeSingleTurn` -> `execute` -> `buildRequest`, which copies
+ // `max_tokens` into `generation.maxOutputTokens`), so this is a refusal a
+ // caller can actually provoke, not a synthetic one.
const history = [{ role: 'user' as const, content: 'summarize' }]
const rejected = provider.completeSingleTurn(history, { max_tokens: 16_385 })
diff --git a/mcp-host/src/llm/__tests__/grokSubscription.test.ts b/mcp-host/src/llm/__tests__/grokSubscription.test.ts
index 553dc2682..fafa49f77 100644
--- a/mcp-host/src/llm/__tests__/grokSubscription.test.ts
+++ b/mcp-host/src/llm/__tests__/grokSubscription.test.ts
@@ -398,8 +398,8 @@ 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:363-377` - the one that
- // measures real bytes. #728 classified the message count correctly and left
+ // canonical-hash path (`hashCanonicalGrokRequest` in `execute`) - 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
// "Connection Error", a label that reads as transient.
const oversized = [
@@ -449,7 +449,7 @@ describe('GrokSubscriptionProvider', () => {
const wired = deps()
const provider = new GrokSubscriptionProvider('grok-4.6', wired as never)
// The `messages[i].toolCalls` bound has no guard ahead of it in this file -
- // unlike the message count, which `execute` refuses itself at `:352`. It can
+ // unlike the message count, which `execute` refuses itself before hashing. It can
// only be reached through the canonical hash, which makes it the one size
// refusal whose classification depends entirely on the regex list. 257 is
// the right number because #728 raised `maxToolCalls` to 256 (`8e12900e6`);
@@ -493,8 +493,8 @@ describe('GrokSubscriptionProvider', () => {
const provider = new GrokSubscriptionProvider('grok-4.6', wired as never)
// `checkStructure` runs before `JSON.stringify`, so a structure with more
// elements than the byte cap is refused by the element bound
- // (`grok-provider-attempt-contract/index.cjs:214`) and never by the byte
- // measurement at `:414`. This test is the runtime consumer of that message
+ // (`checkStructure` in `grok-provider-attempt-contract/index.cjs`) and never
+ // by the byte measurement in `parseGrokCompletionRequestV1`. This test is the runtime consumer of that message
// rename: without it nothing on the Grok path observes the difference
// between the element bound and the byte bound. The suffix is also why the
// byte pattern is matched as a prefix - anchoring it at both ends would drop
@@ -600,11 +600,12 @@ describe('GrokSubscriptionProvider', () => {
// The negative half of the partition: a mutation that collapses the ternary
// to `request_limit_exceeded` turns this test red.
// `generation.maxOutputTokens is out of range`
- // (`grok-provider-attempt-contract/index.cjs:376`) is a `limit` refusal that
+ // (`parseGeneration` in `grok-provider-attempt-contract/index.cjs`) is a `limit` refusal that
// 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:291-294` -> `:477`), so this is a
+ // caller unclamped (`completeSingleTurn` -> `execute` -> `buildRequest`,
+ // which copies `max_tokens` into `generation.maxOutputTokens`), 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 f70eb82a2..06536535b 100644
--- a/mcp-host/src/llm/codexSubscription.ts
+++ b/mcp-host/src/llm/codexSubscription.ts
@@ -41,10 +41,12 @@ export type CodexAttemptContext = {
* The contract `limit` refusals that mean "this turn carries too much".
*
* Of the `fail('limit', …)` checks on a request, only these are about
- * conversation volume: the real byte bound (`index.cjs:570`) and its
- * non-image share on a V2 request (`:579`), the element bound that proxies it
- * (`:332`), `maxMessages` (`:389`) and `messages[i].toolCalls` (`:418`).
- * All four are "this conversation is too long", which is exactly what
+ * conversation volume, all in `llm-provider-attempt-contract/index.cjs`: the
+ * real byte bound and its non-image share on a V2 request (both in
+ * `parseCodexCompletionRequestRoot`), the element bound that proxies it
+ * (`checkStructure`), and `maxMessages` and `messages[i].toolCalls` (both in
+ * `parseMessages`).
+ * All five 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
@@ -53,12 +55,14 @@ export type CodexAttemptContext = {
* `maxToolCalls` also bounds every response, so only history produced by
* another provider can carry an over-long `toolCalls` array.
*
- * The others are not. Nesting depth (`:313`, `:354`),
- * `generation.maxOutputTokens` and `deadlineMs` out of range are malformed or
+ * The others are not. Nesting depth (`checkStructure`, `assertFiniteTree`),
+ * `generation.maxOutputTokens` (`parseGeneration`) and `deadlineMs`
+ * (`parseCodexCompletionRequestRoot`) 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
* compaction loop that cannot converge. They stay `invalid_request`, which is
- * what `subscriptionRequestHash.test.ts:155-168` pins for the over-deep schema.
+ * what "fails an over-deep tool schema locally without a stack overflow" in
+ * `subscriptionRequestHash.test.ts` pins for the over-deep schema.
* The image budgets belong to the attachments, not the conversation: a `size`
* one is `attachment_too_large` (see `ATTACHMENT_BUDGET_REFUSALS`), the
* `maxImages` `count` one stays `invalid_request`.
diff --git a/mcp-host/src/llm/grokSubscription.ts b/mcp-host/src/llm/grokSubscription.ts
index 4e0058a8d..c024f1734 100644
--- a/mcp-host/src/llm/grokSubscription.ts
+++ b/mcp-host/src/llm/grokSubscription.ts
@@ -36,17 +36,19 @@ export type GrokAttemptContext = {
/**
* The contract `limit` refusals that mean "this turn carries too much".
*
- * 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
+ * The Grok twin of `CONTEXT_LENGTH_REFUSALS` in `codexSubscription.ts`. The two
+ * are deliberate duplicates, not an accident: the header of
+ * `grok-provider-attempt-contract/index.cjs` 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
* code. The cost of the duplication is that each copy needs its own tests, which
* is what T-C-grok, T-C2-grok, T-C3-grok and T-C5-grok are for. If you change
* one list, read the other.
*
* `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`).
+ * volume: the real byte bound (`parseGrokCompletionRequestV1`), the element
+ * bound that proxies it (`checkStructure`), and `maxMessages` and
+ * `messages[i].toolCalls` (both in `parseMessages`).
* 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,
@@ -56,13 +58,15 @@ export type GrokAttemptContext = {
* `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
- * 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 compaction loop that cannot converge. They stay `invalid_request`, which is
- * what `subscriptionRequestHash.test.ts:155-168` pins for the over-deep schema
- * across both providers.
+ * The other four are not. Nesting depth (`checkStructure`, `assertFiniteTree`),
+ * `generation.maxOutputTokens` (`parseGeneration`) and `deadlineMs`
+ * (`parseGrokCompletionRequestV1`) 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 compaction loop that
+ * cannot converge. They stay `invalid_request`, which is what "fails an
+ * over-deep tool schema locally without a stack overflow" in
+ * `subscriptionRequestHash.test.ts` pins for the over-deep schema across both
+ * providers.
*
* `hashCanonicalGrokRequest` returns `{ ok, code, message }` and nothing else,
* so the message is the only discriminator available at this boundary (#731).