Skip to content

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

TypeScript

docs: document the 8 MiB request cap and subscription context windows (#731)

Alfredo Lopezad29fb62cd51
diff --git a/docs/architecture/codex-subscription-transport-contract.md b/docs/architecture/codex-subscription-transport-contract.md
index bd998407a..9ab821fe5 100644
--- a/docs/architecture/codex-subscription-transport-contract.md
+++ b/docs/architecture/codex-subscription-transport-contract.md
@@ -51,7 +51,7 @@ one physical execution per ticket. A retry or fallback must mint a new attempt.
| Limit | Value |
| -------------------- | ------- |
-| maxRequestBodyBytes | 1048576 |
+| maxRequestBodyBytes | 8388608 |
| maxMessages | 1024 |
| maxToolCalls | 256 |
| maxOutputTokens | 16384 |
@@ -63,7 +63,7 @@ one physical execution per ticket. A retry or fallback must mint a new attempt.
Tool definitions have no independent count ceiling in the Evenfire request
contract. The entire serialized request, including all definitions, remains
-bounded by `maxRequestBodyBytes` (1 MiB). Every definition still undergoes
+bounded by `maxRequestBodyBytes` (8 MiB). Every definition still undergoes
name, schema, finite-value and unknown-field validation. `maxToolCalls` (256)
bounds calls in each assistant history message and each newly returned
response. The proxy buffers tool calls until successful completion and
@@ -83,6 +83,25 @@ which schemas are sent, without changing the approved catalog or permissions.
An oversized explicit direct request fails before authorization rather than
silently truncating tools or changing presentation.
+`maxRequestBodyBytes` is 8388608 (8 MiB) for every request that carries no
+image (#731). It covers a 1M-token window serialized as escaped JSON. The
+proxy's body limit is that cap plus a 16 KiB envelope allowance, the
+workflow-approval-gateway authorize location sets `client_max_body_size` to
+the same value, and the proxy admits bodies against an in-flight byte budget
+before parsing them.
+
+The Host starts compaction at 80% of the model's context window, so the window
+decides how much of that cap a conversation can use. The proxy keeps the
+catalog's `context_window` field when it is a positive integer no larger than
+2147483647, the ceiling of the Postgres `INTEGER` column
+`llm_allowed_models.context_window_tokens`, and omits it otherwise.
+`max_context_window` is an opt-in upstream extension and is not read.
+control-api stores the value on every catalog sync; a sync whose catalog omits
+the field keeps the stored value rather than clearing it. When no window is
+stored, the Host uses 256000 for `codex-subscription`. It logs
+`context_window_resolved` once per task with the provider, the model, the
+window and its source (`catalog` or `default`).
+
### Compatibility and deployment order
The V1 wire fields and canonical hash projection are unchanged. Previously
diff --git a/docs/architecture/grok-subscription-transport-contract.md b/docs/architecture/grok-subscription-transport-contract.md
index 070b143b7..aaa42a481 100644
--- a/docs/architecture/grok-subscription-transport-contract.md
+++ b/docs/architecture/grok-subscription-transport-contract.md
@@ -126,6 +126,11 @@ Owned by `@clerum/grok-provider-attempt-contract`, a separate module from Codex
message, not the conversation, and the 1:4 spread between the two numbers is a
design choice rather than an arithmetic requirement: a turn of N calls adds
N+1 messages, so a full 256-call turn occupies 257 of the 1024 message slots.
+`maxRequestBodyBytes` is 8388608 (8 MiB) for every request that carries no
+image, as for Codex (#731). It covers a 1M-token window serialized as escaped
+JSON. The proxy's body limit is that cap plus a 16 KiB envelope allowance,
+and the proxy admits bodies against an in-flight byte budget before parsing
+them.
All three enforcement points read this module — the control-api authorizer,
`grok-llm-proxy` and the Host — so a deployment that mixes versions rejects
@@ -158,6 +163,15 @@ because the contract package carries no version identity a caller could
present: the proxy has no way to tell which bound the Host on the other end
was built with.
+The context window follows the same rules as Codex. The proxy keeps the
+catalog's `context_window` field, the name the Grok CLI model cache uses, when
+it is a positive integer no larger than 2147483647 (the Postgres `INTEGER`
+ceiling of `llm_allowed_models.context_window_tokens`), and omits it
+otherwise. control-api stores it on every catalog sync and keeps the stored
+value when a later catalog omits the field. When no window is stored, the Host
+uses 256000 for `grok-subscription` and logs `context_window_resolved` once per
+task with the window and its source (`catalog` or `default`).
+
Proxy robustness (both proxies):
- Admin catalog and connection-test upstream calls have a 15 s deadline that
@@ -250,7 +264,8 @@ Stable codes: `insufficient_scope`, `no_grant`, `model_not_allowed`,
code instead of `LLM_MODEL_OVERLOADED`.
- `tool_call_arguments_exceeded`: the `arguments` text retained across one
response's pending tool calls crossed `MAX_TOOL_CALL_ARGUMENT_CHARS`
- (`grok-llm-proxy/src/grokTransport.ts`, 1 MiB). `maxToolCalls` bounds how
+ (`grok-llm-proxy/src/grokTransport.ts`, equal to `maxRequestBodyBytes`,
+ 8 MiB). `maxToolCalls` bounds how
many calls a response may carry, never how large each one is, and the SSE
buffer guard cannot see this: it bounds the unparsed tail between two `\n\n`
boundaries and is reset on every read. Delivered like
diff --git a/mcp-host/README.md b/mcp-host/README.md
index 212f4ff99..c4af62c23 100644
--- a/mcp-host/README.md
+++ b/mcp-host/README.md
@@ -44,7 +44,7 @@ MCP Host is a Kubernetes-native service that reads Host CRD configuration and pr
| `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_CONTEXT_MAX_TOKENS` | Token budget used by context compaction when the model's allowlist row carries no context window. `codex-subscription` and `grok-subscription` models use 256000 instead; the Host logs `context_window_resolved` with the window and its source. | `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` |
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 0af82dab6..28a656636 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.398",
+ "version": "0.1.399",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.398",
+ "version": "0.1.399",
"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 6ed0b1bff..7bbc7b65f 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.398",
+ "version": "0.1.399",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {