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.mdindex 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 distinctlyfrom 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 — staydiff --git a/docs/architecture/grok-subscription-transport-contract.md b/docs/architecture/grok-subscription-transport-contract.mdindex 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 forwhoever composes the next turn (`grokProxyErrorMessage`): send a more boundedrequest — 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. TheHost raises it before authorization — so no provider attempt is spent — andmaps 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 distinctlyfrom 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 canonicalhash runs; the other three reach this classification through the hash. Untildiff --git a/mcp-host/README.md b/mcp-host/README.mdindex 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 CRDdiff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.jsonindex 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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, sodiff --git a/mcp-host/src/core/tokenizer/heuristic.ts b/mcp-host/src/core/tokenizer/heuristic.tsindex 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 = 0diff --git a/mcp-host/src/llm/__tests__/codexSubscription.test.ts b/mcp-host/src/llm/__tests__/codexSubscription.test.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.cjsindex 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.cjsindex 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.cjsindex 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.cjsindex 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: