Skip to content

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

TypeScript

docs: correct #731 comments on bounds, tokenizer scope and refusal labels

Alfredo Lopez0333ddf7860b
diff --git a/docs/architecture/codex-subscription-transport-contract.md b/docs/architecture/codex-subscription-transport-contract.md
index 720e2ec80..bd998407a 100644
--- a/docs/architecture/codex-subscription-transport-contract.md
+++ b/docs/architecture/codex-subscription-transport-contract.md
@@ -253,7 +253,7 @@ Stable codes: `insufficient_scope`, `no_grant`, `model_not_allowed`,
as "Conversation Too Long".
Four of the contract's `limit` refusals mean this, and the Host classifies on
- the refusal message because `parse*CompletionRequestV1` returns
+ the refusal message because `hashCanonicalCodexRequest` returns
`{ ok, code, message }` and nothing else:
| Refusal message | Guard |
@@ -273,9 +273,17 @@ Stable codes: `insufficient_scope`, `no_grant`, `model_not_allowed`,
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.
+ because it is fixed differently: every element serializes to at least one
+ byte, so a request of plain JSON data with more elements than the byte cap
+ cannot fit under the byte cap either, and for such a request an
+ element-bound refusal is always also a byte-bound one. A value that
+ `JSON.stringify` drops (a function, a symbol) is still counted, so for other
+ input the element bound can only refuse earlier.
+
+ The byte cap covers the whole request, tool definitions included. A tool
+ catalog that alone exceeds it is refused with the same message and labelled
+ context length, although compaction shrinks only the conversation and cannot
+ bring that request under the cap.
The contract's remaining `limit` refusals — nesting depth,
`generation.maxOutputTokens` and `deadlineMs` out of range — stay
diff --git a/docs/architecture/grok-subscription-transport-contract.md b/docs/architecture/grok-subscription-transport-contract.md
index d6239dd2a..070b143b7 100644
--- a/docs/architecture/grok-subscription-transport-contract.md
+++ b/docs/architecture/grok-subscription-transport-contract.md
@@ -261,8 +261,9 @@ Stable codes: `insufficient_scope`, `no_grant`, `model_not_allowed`,
proxy body carries only the code, the Host turns it into guidance for
whoever composes the next turn (`grokProxyErrorMessage`): send a more bounded
request — fewer items per call, narrower fields, or the work split across
- several smaller calls. The bound and that wording are interim; issue #731
- owns the end-to-end size budget and its own PR replaces both.
+ several smaller calls. The bound and that wording are interim: the #731
+ request-size work classifies this refusal as context length (above) and
+ leaves the bound's value and the wording as they are.
- `request_limit_exceeded` (Host-side only): the turn carries too much. The
Host raises it before authorization — so no provider attempt is spent — and
maps it to `LLM_CONTEXT_LENGTH_EXCEEDED`, not retryable, which the UI shows
@@ -289,9 +290,17 @@ Stable codes: `insufficient_scope`, `no_grant`, `model_not_allowed`,
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.
+ because it is fixed differently: every element serializes to at least one
+ byte, so a request of plain JSON data with more elements than the byte cap
+ cannot fit under the byte cap either, and for such a request an
+ element-bound refusal is always also a byte-bound one. A value that
+ `JSON.stringify` drops (a function, a symbol) is still counted, so for other
+ input the element bound can only refuse earlier.
+
+ The byte cap covers the whole request, tool definitions included. A tool
+ catalog that alone exceeds it is refused with the same message and labelled
+ context length, although compaction shrinks only the conversation and cannot
+ bring that request under the cap.
The message count is refused by the Host's own guard before the canonical
hash runs; the other three reach this classification through the hash. Until
diff --git a/mcp-host/README.md b/mcp-host/README.md
index ca09345a8..212f4ff99 100644
--- a/mcp-host/README.md
+++ b/mcp-host/README.md
@@ -17,49 +17,49 @@ MCP Host is a Kubernetes-native service that reads Host CRD configuration and pr
### Environment Variables
-| Variable | Explanation | Canonical example |
-| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `CLERUM_DEV_MODE` | Enables local/dev bootstrap mode that bypasses Host CRD discovery and reads host/runtime config from env. | `CLERUM_DEV_MODE=true` |
-| `CLERUM_HOST_NAME` | Selects which Host CRD to load in production mode; in non-production fallback it defaults to `dev-host`. | `CLERUM_HOST_NAME=chatllm` |
-| `CLERUM_NAMESPACE` | Sets the Kubernetes namespace used for Host and Secret lookup when running in cluster mode. | `CLERUM_NAMESPACE=mcp-host` |
-| `CLERUM_SERVER_PORT` | Sets the HTTP listen port for the runtime API server. | `CLERUM_SERVER_PORT=8080` |
-| `CLERUM_CONTEXT_MAPPER_URL` | Points to the host-context-controller endpoint used to resolve MCP servers for a context. | `CLERUM_CONTEXT_MAPPER_URL=http://host-context-controller-api-gateway.control-plane.svc.cluster.local:8081` |
-| `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL` | Controls polling interval (milliseconds) for MCP server config changes from context mapper. | `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL=30000` |
-| `HCC_AUTHORITY_MAX_STALENESS_MS` | Maximum time a previously published MCP fleet may survive an unavailable HCC (default 180000 ms; hard-capped at 600000 ms). It must be greater than `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL` in cluster mode; invalid combinations fail startup. Minikube pins 60000 ms for its deterministic staleness E2E. | `HCC_AUTHORITY_MAX_STALENESS_MS=180000` |
-| `CLERUM_HOST_CONFIG` | Provides a full Host spec as JSON in dev mode, overriding provider/model context env composition. | `CLERUM_HOST_CONFIG={"host":"dev-host","contextRef":"dev-context","secretRef":"dev-secret","model":{"provider":"openai","name":"gpt-5.4-mini"}}` |
-| `CLERUM_MODEL_PROVIDER` | Chooses the model provider in dev mode when `CLERUM_HOST_CONFIG` is not set. | `CLERUM_MODEL_PROVIDER=openai` |
-| `CLERUM_MODEL_NAME` | Overrides the default provider model name in dev mode. | `CLERUM_MODEL_NAME=gpt-5.4-mini` |
-| `CLERUM_MCP_SERVERS` | Supplies dev MCP server definitions as JSON so you can run without context mapper. Each entry needs `name`, `contextRef`, `transport`, `enabled`, and a `status` object — a server whose `status.ready` is not `true` is parsed but skipped as "not ready". | `CLERUM_MCP_SERVERS=[{"name":"filesystem","contextRef":"dev-context","transport":{"type":"streamableHttp","url":"http://localhost:3101"},"enabled":true,"status":{"deployed":true,"ready":true}}]` |
-| `CLERUM_MCP_TOOL_TIMEOUT_MS` | Per-call timeout passed to MCP SDK `Client.callTool(...)` requests. The effective timeout is still bounded by any caller workflow or snippet step budget. | `CLERUM_MCP_TOOL_TIMEOUT_MS=1500000` |
-| `CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS` | Maximum total MCP SDK tool-call budget used at the SDK request boundary. Operators may tune it up to the existing workflow step ceiling; invalid values fail closed at runtime. | `CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS=1500000` |
-| `OPENAI_API_KEY` | OpenAI API key used by dev mode when provider selection resolves to OpenAI. | `OPENAI_API_KEY=sk-xxxx` |
-| `CLAUDE_API_KEY` | Anthropic API key used by dev mode when provider selection resolves to Claude. | `CLAUDE_API_KEY=sk-ant-xxxx` |
-| `ZAI_API_KEY` | ZAI API key used by dev mode when provider selection resolves to ZAI. | `ZAI_API_KEY=zai-xxxx` |
-| `BAILIAN_API_KEY` | Bailian API key used by dev mode when provider selection resolves to Bailian/Qwen. | `BAILIAN_API_KEY=ba-xxxx` |
-| `CLERUM_AGENT_TASK_DELAY` | Minimum interval in milliseconds between task dispatches; does not delay individual tool iterations. | `CLERUM_AGENT_TASK_DELAY=3` |
-| `CLERUM_AGENT_MAX_TASK_DURATION` | Maximum active task execution time in milliseconds (24 hours), accumulated across approval resumptions. Approval waiting is excluded. | `CLERUM_AGENT_MAX_TASK_DURATION=86400000` |
-| `CLERUM_AGENT_MAX_TOOL_CALLS` | Maximum LLM/tool iterations per task; each iteration may call multiple tools. Configured per Host process. | `CLERUM_AGENT_MAX_TOOL_CALLS=1000` |
-| `CLERUM_AGENT_MAX_QUEUE_SIZE` | Maximum pending queue size before new tasks are rejected/back-pressured. | `CLERUM_AGENT_MAX_QUEUE_SIZE=100` |
-| `CLERUM_ENABLE_APPROVAL` | Enables the approval gate workflow for tool execution decisions. | `CLERUM_ENABLE_APPROVAL=true` |
-| `CLERUM_APPROVAL_CONFIG` | JSON config for approval policy/channels when not sourced from Host CRD. | `CLERUM_APPROVAL_CONFIG={"defaultPolicy":"designated_approvers","channels":{"telegram":{"enabled":true,"approvers":["123456"]}}}` |
-| `CLERUM_ENABLE_NUDGE` | Enables the nudge controller that pushes model/tool retry guidance when output is rejected. | `CLERUM_ENABLE_NUDGE=false` |
-| `CLERUM_NUDGE_MAX_ITERATIONS` | Maximum number of nudge cycles allowed for a task. | `CLERUM_NUDGE_MAX_ITERATIONS=3` |
-| `CLERUM_CONTEXT_MAX_TOKENS` | Token budget used by context compaction logic before pruning/summarization. | `CLERUM_CONTEXT_MAX_TOKENS=100000` |
-| `CLERUM_COMPACTION_PRE_PRUNE` | Master switch for pre-pruning the history before each LLM call (deduplication, one-lining, JSON truncation, media stripping). On by default; set to `false` to disable every pass at once. | `CLERUM_COMPACTION_PRE_PRUNE=true` |
-| `CLERUM_WORKSPACE_PATH` | Base workspace path used by native tools and workspace-aware operations. | `CLERUM_WORKSPACE_PATH=/workspace` |
-| `CLERUM_SHELL_TIMEOUT` | Maximum execution time in milliseconds for shell native-tool commands. | `CLERUM_SHELL_TIMEOUT=1500000` |
-| `CLERUM_TOOL_TIMEOUT` | Maximum execution time in milliseconds for native tool wrapper calls. This is separate from the MCP SDK request timeout controlled by `CLERUM_MCP_TOOL_TIMEOUT_MS`. | `CLERUM_TOOL_TIMEOUT=1500000` |
-| `CLERUM_HTTP_ALLOWLIST` | Comma-separated allowlist of outbound hosts/URLs allowed for HTTP native tools. With an allowlist set, you can also skip per-call approval by adding `tools: { http_request: false }` under `Host.spec.approval` (see Host CRD). | `CLERUM_HTTP_ALLOWLIST=api.github.com,example.com` |
-| `CLERUM_ENV_ALLOWLIST` | Comma-separated list of environment variables forwarded into native tool execution contexts. | `CLERUM_ENV_ALLOWLIST=PATH,HOME,USER,SHELL,LANG,TERM` |
-| `CLERUM_MEMORY_MAX_SIZE` | Maximum bytes reserved for in-memory native tool buffers/state. | `CLERUM_MEMORY_MAX_SIZE=1048576` |
-| `CLERUM_ENABLE_RESPONSE_ATTACHMENTS` | Enables attachment passthrough in runtime responses when tools return supported media. | `CLERUM_ENABLE_RESPONSE_ATTACHMENTS=true` |
-| `CLERUM_ATTACHMENT_MAX_COUNT` | Maximum number of attachments returned per response. | `CLERUM_ATTACHMENT_MAX_COUNT=3` |
-| `CLERUM_ATTACHMENT_MAX_BYTES` | Maximum decoded size per attachment in bytes (oversized payloads are dropped). | `CLERUM_ATTACHMENT_MAX_BYTES=52428800` |
-| `CLERUM_MEMORY_ENABLED` | Enables workspace memory persistence features. | `CLERUM_MEMORY_ENABLED=true` |
-| `CLERUM_MEMORY_WORKSPACE_PATH` | Sets workspace directory path used when memory mode is enabled. | `CLERUM_MEMORY_WORKSPACE_PATH=/workspace` |
-| `CLERUM_PERSONALIZATION_ENABLED` | Enables identity/personalization seeding behavior. | `CLERUM_PERSONALIZATION_ENABLED=true` |
-| `CLERUM_IDENTITY_SEED` | JSON identity seed used to initialize personalization artifacts when enabled. | `CLERUM_IDENTITY_SEED={"displayName":"Clerum Agent","tone":"concise"}` |
-| `NODE_ENV` | Influences production checks and defaults (for example strict host-name requirement in production). | `NODE_ENV=production` |
+| Variable | Explanation | Canonical example |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CLERUM_DEV_MODE` | Enables local/dev bootstrap mode that bypasses Host CRD discovery and reads host/runtime config from env. | `CLERUM_DEV_MODE=true` |
+| `CLERUM_HOST_NAME` | Selects which Host CRD to load in production mode; in non-production fallback it defaults to `dev-host`. | `CLERUM_HOST_NAME=chatllm` |
+| `CLERUM_NAMESPACE` | Sets the Kubernetes namespace used for Host and Secret lookup when running in cluster mode. | `CLERUM_NAMESPACE=mcp-host` |
+| `CLERUM_SERVER_PORT` | Sets the HTTP listen port for the runtime API server. | `CLERUM_SERVER_PORT=8080` |
+| `CLERUM_CONTEXT_MAPPER_URL` | Points to the host-context-controller endpoint used to resolve MCP servers for a context. | `CLERUM_CONTEXT_MAPPER_URL=http://host-context-controller-api-gateway.control-plane.svc.cluster.local:8081` |
+| `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL` | Controls polling interval (milliseconds) for MCP server config changes from context mapper. | `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL=30000` |
+| `HCC_AUTHORITY_MAX_STALENESS_MS` | Maximum time a previously published MCP fleet may survive an unavailable HCC (default 180000 ms; hard-capped at 600000 ms). It must be greater than `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL` in cluster mode; invalid combinations fail startup. Minikube pins 60000 ms for its deterministic staleness E2E. | `HCC_AUTHORITY_MAX_STALENESS_MS=180000` |
+| `CLERUM_HOST_CONFIG` | Provides a full Host spec as JSON in dev mode, overriding provider/model context env composition. | `CLERUM_HOST_CONFIG={"host":"dev-host","contextRef":"dev-context","secretRef":"dev-secret","model":{"provider":"openai","name":"gpt-5.4-mini"}}` |
+| `CLERUM_MODEL_PROVIDER` | Chooses the model provider in dev mode when `CLERUM_HOST_CONFIG` is not set. | `CLERUM_MODEL_PROVIDER=openai` |
+| `CLERUM_MODEL_NAME` | Overrides the default provider model name in dev mode. | `CLERUM_MODEL_NAME=gpt-5.4-mini` |
+| `CLERUM_MCP_SERVERS` | Supplies dev MCP server definitions as JSON so you can run without context mapper. Each entry needs `name`, `contextRef`, `transport`, `enabled`, and a `status` object — a server whose `status.ready` is not `true` is parsed but skipped as "not ready". | `CLERUM_MCP_SERVERS=[{"name":"filesystem","contextRef":"dev-context","transport":{"type":"streamableHttp","url":"http://localhost:3101"},"enabled":true,"status":{"deployed":true,"ready":true}}]` |
+| `CLERUM_MCP_TOOL_TIMEOUT_MS` | Per-call timeout passed to MCP SDK `Client.callTool(...)` requests. The effective timeout is still bounded by any caller workflow or snippet step budget. | `CLERUM_MCP_TOOL_TIMEOUT_MS=1500000` |
+| `CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS` | Maximum total MCP SDK tool-call budget used at the SDK request boundary. Operators may tune it up to the existing workflow step ceiling; invalid values fail closed at runtime. | `CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS=1500000` |
+| `OPENAI_API_KEY` | OpenAI API key used by dev mode when provider selection resolves to OpenAI. | `OPENAI_API_KEY=sk-xxxx` |
+| `CLAUDE_API_KEY` | Anthropic API key used by dev mode when provider selection resolves to Claude. | `CLAUDE_API_KEY=sk-ant-xxxx` |
+| `ZAI_API_KEY` | ZAI API key used by dev mode when provider selection resolves to ZAI. | `ZAI_API_KEY=zai-xxxx` |
+| `BAILIAN_API_KEY` | Bailian API key used by dev mode when provider selection resolves to Bailian/Qwen. | `BAILIAN_API_KEY=ba-xxxx` |
+| `CLERUM_AGENT_TASK_DELAY` | Minimum interval in milliseconds between task dispatches; does not delay individual tool iterations. | `CLERUM_AGENT_TASK_DELAY=3` |
+| `CLERUM_AGENT_MAX_TASK_DURATION` | Maximum active task execution time in milliseconds (24 hours), accumulated across approval resumptions. Approval waiting is excluded. | `CLERUM_AGENT_MAX_TASK_DURATION=86400000` |
+| `CLERUM_AGENT_MAX_TOOL_CALLS` | Maximum LLM/tool iterations per task; each iteration may call multiple tools. Configured per Host process. | `CLERUM_AGENT_MAX_TOOL_CALLS=1000` |
+| `CLERUM_AGENT_MAX_QUEUE_SIZE` | Maximum pending queue size before new tasks are rejected/back-pressured. | `CLERUM_AGENT_MAX_QUEUE_SIZE=100` |
+| `CLERUM_ENABLE_APPROVAL` | Enables the approval gate workflow for tool execution decisions. | `CLERUM_ENABLE_APPROVAL=true` |
+| `CLERUM_APPROVAL_CONFIG` | JSON config for approval policy/channels when not sourced from Host CRD. | `CLERUM_APPROVAL_CONFIG={"defaultPolicy":"designated_approvers","channels":{"telegram":{"enabled":true,"approvers":["123456"]}}}` |
+| `CLERUM_ENABLE_NUDGE` | Enables the nudge controller that pushes model/tool retry guidance when output is rejected. | `CLERUM_ENABLE_NUDGE=false` |
+| `CLERUM_NUDGE_MAX_ITERATIONS` | Maximum number of nudge cycles allowed for a task. | `CLERUM_NUDGE_MAX_ITERATIONS=3` |
+| `CLERUM_CONTEXT_MAX_TOKENS` | Token budget used by context compaction logic before pruning/summarization. | `CLERUM_CONTEXT_MAX_TOKENS=100000` |
+| `CLERUM_COMPACTION_PRE_PRUNE` | Master switch for pre-pruning the history (deduplication, one-lining, JSON truncation, media stripping). It runs only once the history reaches the compaction threshold (80% of the context window), before any compaction tier is chosen, and at history rehydration under the same threshold. On by default; set to `false` to disable every pass at once. | `CLERUM_COMPACTION_PRE_PRUNE=true` |
+| `CLERUM_WORKSPACE_PATH` | Base workspace path used by native tools and workspace-aware operations. | `CLERUM_WORKSPACE_PATH=/workspace` |
+| `CLERUM_SHELL_TIMEOUT` | Maximum execution time in milliseconds for shell native-tool commands. | `CLERUM_SHELL_TIMEOUT=1500000` |
+| `CLERUM_TOOL_TIMEOUT` | Maximum execution time in milliseconds for native tool wrapper calls. This is separate from the MCP SDK request timeout controlled by `CLERUM_MCP_TOOL_TIMEOUT_MS`. | `CLERUM_TOOL_TIMEOUT=1500000` |
+| `CLERUM_HTTP_ALLOWLIST` | Comma-separated allowlist of outbound hosts/URLs allowed for HTTP native tools. With an allowlist set, you can also skip per-call approval by adding `tools: { http_request: false }` under `Host.spec.approval` (see Host CRD). | `CLERUM_HTTP_ALLOWLIST=api.github.com,example.com` |
+| `CLERUM_ENV_ALLOWLIST` | Comma-separated list of environment variables forwarded into native tool execution contexts. | `CLERUM_ENV_ALLOWLIST=PATH,HOME,USER,SHELL,LANG,TERM` |
+| `CLERUM_MEMORY_MAX_SIZE` | Maximum bytes reserved for in-memory native tool buffers/state. | `CLERUM_MEMORY_MAX_SIZE=1048576` |
+| `CLERUM_ENABLE_RESPONSE_ATTACHMENTS` | Enables attachment passthrough in runtime responses when tools return supported media. | `CLERUM_ENABLE_RESPONSE_ATTACHMENTS=true` |
+| `CLERUM_ATTACHMENT_MAX_COUNT` | Maximum number of attachments returned per response. | `CLERUM_ATTACHMENT_MAX_COUNT=3` |
+| `CLERUM_ATTACHMENT_MAX_BYTES` | Maximum decoded size per attachment in bytes (oversized payloads are dropped). | `CLERUM_ATTACHMENT_MAX_BYTES=52428800` |
+| `CLERUM_MEMORY_ENABLED` | Enables workspace memory persistence features. | `CLERUM_MEMORY_ENABLED=true` |
+| `CLERUM_MEMORY_WORKSPACE_PATH` | Sets workspace directory path used when memory mode is enabled. | `CLERUM_MEMORY_WORKSPACE_PATH=/workspace` |
+| `CLERUM_PERSONALIZATION_ENABLED` | Enables identity/personalization seeding behavior. | `CLERUM_PERSONALIZATION_ENABLED=true` |
+| `CLERUM_IDENTITY_SEED` | JSON identity seed used to initialize personalization artifacts when enabled. | `CLERUM_IDENTITY_SEED={"displayName":"Clerum Agent","tone":"concise"}` |
+| `NODE_ENV` | Influences production checks and defaults (for example strict host-name requirement in production). | `NODE_ENV=production` |
### Host CRD
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 519fc9578..0335f54a9 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.393",
+ "version": "0.1.394",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.393",
+ "version": "0.1.394",
"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 1508d09fb..3c10bca26 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.393",
+ "version": "0.1.394",
"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 8f9a96cd9..e2e0bfccd 100644
--- a/mcp-host/src/__tests__/fixtures/minifiedMcpResult.ts
+++ b/mcp-host/src/__tests__/fixtures/minifiedMcpResult.ts
@@ -3,10 +3,12 @@
* byte size, shaped like what an MCP server actually returns (contact records
* from a CRM/outreach integration).
*
- * 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 in `core/tokenizer/heuristic.ts`.
+ * The payload shape is the point, not the size. A word count under-reads dense
+ * minified JSON because whitespace is rare in it: a 33,313-character result of
+ * seed 1 splits into 1,522 "words" (~1,980 tokens at the old ×1.3) against
+ * ~8,330 at four characters per token. That was the defect `heuristicCount`
+ * carried until #731, and the one `heuristicCountTools` 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.
@@ -84,7 +86,7 @@ function contact(rnd: () => number, index: number): Record<string, unknown> {
*
* Records are serialized one at a time and the envelope length is computed
* exactly at each step, so the result overshoots the target by at most one
- * record (~400 characters). F-1 pins the overshoot at +10%.
+ * record (555–605 characters for seed 1). F-1 pins the overshoot at +10%.
*/
export function minifiedMcpResult(seed: number, targetBytes: number): string {
if (!Number.isInteger(seed)) {
diff --git a/mcp-host/src/core/tokenizer/__tests__/heuristic.test.ts b/mcp-host/src/core/tokenizer/__tests__/heuristic.test.ts
index ba0c43e0a..ef13a1865 100644
--- a/mcp-host/src/core/tokenizer/__tests__/heuristic.test.ts
+++ b/mcp-host/src/core/tokenizer/__tests__/heuristic.test.ts
@@ -30,9 +30,9 @@ describe('heuristicCount', () => {
it('T-A1 counts minified JSON by characters, not by whitespace-separated words', () => {
// #731 — a tool result carrying dense minified JSON is the payload shape
- // that breaks a word count. `heuristicCountTools` already applies
- // `ceil(chars / 4)` for exactly this reason (see its comment); messages,
- // where tool RESULTS live, never got the same correction.
+ // that breaks a word count. `heuristicCountTools` applied `ceil(chars / 4)`
+ // for exactly this reason before #731; messages, where tool RESULTS live,
+ // counted words until #731 gave them the same measure.
const content = minifiedMcpResult(1, 33_000)
const msg: ChatMessage = {
role: 'tool',
diff --git a/mcp-host/src/core/tokenizer/fallbackTokenCounter.ts b/mcp-host/src/core/tokenizer/fallbackTokenCounter.ts
index ce66616c7..5ca3d1315 100644
--- a/mcp-host/src/core/tokenizer/fallbackTokenCounter.ts
+++ b/mcp-host/src/core/tokenizer/fallbackTokenCounter.ts
@@ -1,13 +1,13 @@
/**
- * Heuristic fallback counter for providers without a native token-counting
- * API or compatible tokenizer (ZAI, Bailian, and any future OpenAI-compatible
- * shim with a custom backend).
+ * Heuristic fallback counter for every provider whose registry descriptor
+ * declares `tokenizer: 'fallback'` (`registryCore.ts`): all of them except
+ * `openai` and `claude`, including `codex-subscription` and `grok-subscription`.
*
- * Bias factor: 1.3× over the `ceil(chars / 4) + 4` heuristic to over-estimate
- * (it biased the word-count heuristic the same way before #731).
- * Empirically the heuristic mis-estimates by ±25-40% against actual provider
- * usage; biasing high reduces overflow risk at the cost of slightly earlier
- * compaction.
+ * Bias factor: 1.3× over the byte-based `ceil(bytes / 4) + 4` heuristic, to
+ * over-estimate. The ±25-40% error that motivated the bias was measured on the
+ * word-count heuristic this replaced in #731; the byte count has not been
+ * measured against provider usage. Biasing high reduces overflow risk at the
+ * cost of slightly earlier compaction.
*
* `recordObservedUsage` matters here MORE than for the precise counters —
* the provider's billed `input_tokens` is literally the ground truth, so
diff --git a/mcp-host/src/core/tokenizer/heuristic.ts b/mcp-host/src/core/tokenizer/heuristic.ts
index d5f657b64..3546cd664 100644
--- a/mcp-host/src/core/tokenizer/heuristic.ts
+++ b/mcp-host/src/core/tokenizer/heuristic.ts
@@ -1,7 +1,8 @@
/**
- * Heuristic token estimator — the legacy fallback shared by all `TokenCounter`
- * implementations. Extracted from `core/conversation/compaction.ts` so the
- * counters can use it without circular imports.
+ * Heuristic token estimator shared by all `TokenCounter` implementations, and
+ * the count that selects the compaction tier by default (see the last paragraph
+ * below). Extracted from `core/conversation/compaction.ts` so the counters can
+ * use it without circular imports.
*
* Formula: `ceil(bytes / 4) + 4` per message, where `bytes` is the UTF-8 length
* of the text as JSON serializes it — the standard byte-pair-encoding
@@ -45,7 +46,9 @@ 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. Walks the same field as `openaiTokenCounter.ts:58-62` (#731).
+ // overhead alone (#731). `openaiTokenCounter.ts:58-62` 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 ?? []) {
total += Math.ceil(jsonBytes(tc.arguments ?? {}) / 4)
}
@@ -56,20 +59,21 @@ export function heuristicCount(messages: ChatMessage[]): number {
/**
* Estimate the token cost of tool schemas with a byte-based heuristic
* (`ceil(bytes / 4) + 4` per tool, bytes as JSON serializes them) — the same
- * formula `heuristicCount` uses,
- * which this function had to itself until #731. Tool schemas are dense minified
- * JSON with virtually no whitespace, so a word count collapses the whole
- * `parameters` object into a handful of "words" and underestimates by roughly
- * 4× (a 173-char schema → ~11 word-tokens vs ~44 real tokens). The `chars / 4`
- * ratio is the standard byte-pair-encoding approximation and is a far better
- * fit for this payload shape — and, as #731 established, for tool results too.
+ * formula `heuristicCount` uses, which this function had to itself until #731.
+ * Tool schemas are dense minified JSON with virtually no whitespace, so a word
+ * count collapses the whole `parameters` object into a handful of "words" and
+ * underestimates by roughly 4× (a 173-char schema → ~11 word-tokens vs ~44 real
+ * tokens). The `bytes / 4` ratio is the standard byte-pair-encoding
+ * approximation and is a far better fit for this payload shape — and, as #731
+ * established, for tool results too.
*
* The estimate also covers the same surface OpenAI's exact tokenizer bills for
* a tool: `name` + `description` + `JSON.stringify(parameters)` — not just
* `parameters` alone. The `+4` per-item framing overhead mirrors
* `heuristicCount`. This stays a heuristic approximation for the providers that
- * have no synchronous exact tokenizer (Anthropic, and the zai/bailian fallback)
- * — it is never exact, only closer than the old word count.
+ * have no synchronous exact tokenizer (Anthropic, and every provider on the
+ * `'fallback'` tokenizer, the subscriptions included) — it is never exact, only
+ * closer than the old word count.
*/
export function heuristicCountTools(tools: ToolDefinition[]): number {
let total = 0
diff --git a/mcp-host/src/llm/__tests__/codexSubscription.test.ts b/mcp-host/src/llm/__tests__/codexSubscription.test.ts
index 69606d1f2..05789d738 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:337-350` - the one that measures real bytes.
+ // at `codexSubscription.ts:339-352` - 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' },
@@ -361,7 +361,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:265-267` -> `:450`), so this is a refusal a caller
+ // (`codexSubscription.ts:267-270` -> `:452`), 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__/contextOverrunJourney.test.ts b/mcp-host/src/llm/__tests__/contextOverrunJourney.test.ts
index ece90485e..a8c6d5749 100644
--- a/mcp-host/src/llm/__tests__/contextOverrunJourney.test.ts
+++ b/mcp-host/src/llm/__tests__/contextOverrunJourney.test.ts
@@ -299,9 +299,9 @@ describe('#731 context-overrun journey', () => {
const err = await rejected.catch((e: unknown) => e)
// What the user is shown depends on this: `ContextLengthExceeded` reads as
- // "Conversation Too Long", while the `invalid_request` this returns today
- // reaches the UI as a retryable "Connection Error" and invites a retry that
- // reproduces the same failure.
+ // "Conversation Too Long", while the `invalid_request` returned before #731
+ // reached the UI as "Connection Error", a label that reads as transient and
+ // invites a retry that reproduces the same failure.
expect(provider.classifyError(err)).toMatchObject({
code: LlmErrorCode.ContextLengthExceeded,
retryable: false,
diff --git a/mcp-host/src/llm/__tests__/grokSubscription.test.ts b/mcp-host/src/llm/__tests__/grokSubscription.test.ts
index db74d0905..5d9e5794d 100644
--- a/mcp-host/src/llm/__tests__/grokSubscription.test.ts
+++ b/mcp-host/src/llm/__tests__/grokSubscription.test.ts
@@ -356,10 +356,10 @@ 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:357-372` - the one that
+ // canonical-hash path at `grokSubscription.ts:363-377` - 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".
+ // "Connection Error", a label that reads as transient.
const oversized = [
{ role: 'system' as const, content: 'you are a helpful assistant' },
{ role: 'user' as const, content: 'list every contact' },
@@ -405,10 +405,10 @@ 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 `:340`. It can
+ // unlike the message count, which `execute` refuses itself at `:352`. 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 (`d3a051348`);
+ // the right number because #728 raised `maxToolCalls` to 256 (`8e12900e6`);
// against the earlier bound of 64 this message would not have overrun.
const calls = Array.from({ length: 257 }, (_, index) => ({
id: `call_${index}`,
@@ -450,11 +450,11 @@ describe('GrokSubscriptionProvider', () => {
// `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 that message
- // rename has lacked: the PR renamed the string, and until the ternary below
- // exists nothing on the Grok path can observe the difference. The suffix is
- // also why the byte pattern is matched as a prefix - anchoring it at both
- // ends would drop this refusal back to `invalid_request` unnoticed.
+ // measurement at `:414`. 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
+ // this refusal back to `invalid_request` unnoticed.
const history = [
{ role: 'user' as const, content: 'summarize the export' },
{
@@ -500,14 +500,14 @@ describe('GrokSubscriptionProvider', () => {
it('T-C5-grok keeps an out-of-range maxOutputTokens out of the context-length taxonomy (#731)', async () => {
const wired = deps()
const provider = new GrokSubscriptionProvider('grok-4.6', wired as never)
- // The negative half of the partition, and the only Grok test a mutation
- // that collapses the ternary to `request_limit_exceeded` can turn red.
+ // 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
// 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:287` -> `:471`), so this is a
+ // caller unclamped (`grokSubscription.ts:291-294` -> `:477`), 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 01c588543..0c25af701 100644
--- a/mcp-host/src/llm/codexSubscription.ts
+++ b/mcp-host/src/llm/codexSubscription.ts
@@ -341,9 +341,9 @@ export class CodexSubscriptionProvider implements SingleTurnProvider {
// A size refusal (bytes, element bound, message count, tool-call count)
// is a context-length failure, not a malformed request; it is thrown
// before authorize and dispatch so no provider attempt is spent.
- // Reported as `invalid_request` it reached the UI as a retryable
- // "Connection Error" and invited a retry that reproduced it (#731). The
- // message-count guard above already used this classification.
+ // Reported as `invalid_request` it reached the UI as "Connection Error",
+ // a label that reads as transient, and invited a retry that reproduced it
+ // (#731). The message-count guard above already used this classification.
throw new CodexAuthorizeError(
isContextLengthRefusal(canonical.code, canonical.message)
? 'request_limit_exceeded'
diff --git a/mcp-host/src/llm/grokSubscription.ts b/mcp-host/src/llm/grokSubscription.ts
index ef286fbfd..3b6d85e5e 100644
--- a/mcp-host/src/llm/grokSubscription.ts
+++ b/mcp-host/src/llm/grokSubscription.ts
@@ -365,9 +365,9 @@ export class GrokSubscriptionProvider implements SingleTurnProvider {
// A size refusal (bytes, element bound, message count, tool-call count)
// is a context-length failure, not a malformed request; it is thrown
// before authorize and dispatch so no provider attempt is spent.
- // Reported as `invalid_request` it reached the UI as a retryable
- // "Connection Error" and invited a retry that reproduced it (#731). The
- // message-count guard above already used this classification, and #728
+ // Reported as `invalid_request` it reached the UI as "Connection Error",
+ // a label that reads as transient, and invited a retry that reproduced it
+ // (#731). The message-count guard above already used this classification, and #728
// left this path behind when it added that guard.
throw new CodexAuthorizeError(
isContextLengthRefusal(canonical.code, canonical.message)
diff --git a/packages/grok-provider-attempt-contract/index.cjs b/packages/grok-provider-attempt-contract/index.cjs
index d0fce11f2..8ec088aef 100644
--- a/packages/grok-provider-attempt-contract/index.cjs
+++ b/packages/grok-provider-attempt-contract/index.cjs
@@ -208,9 +208,11 @@ function checkStructure(value, maxDepth) {
// 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.
// 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).
+ // rather than given a constant of its own: every element serializes to
+ // at least one byte, so a request of plain JSON data with more elements
+ // than the byte cap cannot fit under it either (#731). A value that
+ // JSON.stringify drops (a function, a symbol) is still counted here, so
+ // for such input this bound can only refuse earlier, never later.
return fail('limit', 'request exceeds maxRequestBodyBytes element bound')
}
for (const child of children) {
@@ -410,6 +412,10 @@ function parseGrokCompletionRequestV1(input) {
} catch {
return fail('invalid', 'request is not JSON-serializable')
}
+ // The byte count covers the whole request, tool definitions included. A
+ // tool catalog that alone exceeds the cap is refused with this message and
+ // the Host labels it context length, although compaction shrinks only the
+ // conversation and cannot bring such a request under the cap.
if (encoded > LIMITS.maxRequestBodyBytes) {
return fail('limit', 'request exceeds maxRequestBodyBytes')
}
diff --git a/packages/grok-provider-attempt-contract/index.test.cjs b/packages/grok-provider-attempt-contract/index.test.cjs
index 373cbd8e2..8793096d3 100644
--- a/packages/grok-provider-attempt-contract/index.test.cjs
+++ b/packages/grok-provider-attempt-contract/index.test.cjs
@@ -315,10 +315,10 @@ test('opaque canonical names remain bounded by serialized UTF-8 request bytes',
})
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. Compaction is the remedy either way; the
+ // Same defect as the Codex contract's: before #731 the element count inside
+ // `checkStructure` and the real byte measurement refused with the identical
+ // sentence, so a user report of `request exceeds maxRequestBodyBytes` could
+ // not name the guard that fired. Compaction is the remedy either way; the
// distinct wording buys diagnosis, not a different fix (#731).
//
// What makes the two guards separable here is ORDER, not size:
diff --git a/packages/llm-provider-attempt-contract/index.cjs b/packages/llm-provider-attempt-contract/index.cjs
index 6fdf268e4..9e8a5e23d 100644
--- a/packages/llm-provider-attempt-contract/index.cjs
+++ b/packages/llm-provider-attempt-contract/index.cjs
@@ -187,9 +187,11 @@ function checkStructure(value, maxDepth) {
// 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.
// 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).
+ // rather than given a constant of its own: every element serializes to
+ // at least one byte, so a request of plain JSON data with more elements
+ // than the byte cap cannot fit under it either (#731). A value that
+ // JSON.stringify drops (a function, a symbol) is still counted here, so
+ // for such input this bound can only refuse earlier, never later.
return fail('limit', 'request exceeds maxRequestBodyBytes element bound')
}
for (const child of children) {
@@ -387,6 +389,10 @@ function parseCodexCompletionRequestV1(input) {
} catch {
return fail('invalid', 'request is not JSON-serializable')
}
+ // The byte count covers the whole request, tool definitions included. A
+ // tool catalog that alone exceeds the cap is refused with this message and
+ // the Host labels it context length, although compaction shrinks only the
+ // conversation and cannot bring such a request under the cap.
if (encoded > LIMITS.maxRequestBodyBytes) {
return fail('limit', 'request exceeds maxRequestBodyBytes')
}
diff --git a/packages/llm-provider-attempt-contract/index.test.cjs b/packages/llm-provider-attempt-contract/index.test.cjs
index 9aa16c110..f80796d8e 100644
--- a/packages/llm-provider-attempt-contract/index.test.cjs
+++ b/packages/llm-provider-attempt-contract/index.test.cjs
@@ -315,10 +315,10 @@ test('large catalogs remain bounded by serialized request bytes including UTF-8'
})
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. Compaction is the remedy either way;
+ // Before #731 two different guards refused with the identical sentence: the
+ // element count inside `checkStructure` and the real byte measurement that
+ // the two tests above pin. A user reporting `request exceeds
+ // maxRequestBodyBytes` therefore could not say which one fired. Compaction is the remedy either way;
// the distinct wording buys diagnosis, not a different fix (#731).
//
// What makes the two guards separable here is ORDER, not size: