Skip to content

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

TypeScript

docs(grok): document the limit taxonomy and correct a stale limit comment

Alfredo Lopezca5ed25b141e
diff --git a/docs/architecture/grok-subscription-transport-contract.md b/docs/architecture/grok-subscription-transport-contract.md
index 97fa74ca3..e3a3ede01 100644
--- a/docs/architecture/grok-subscription-transport-contract.md
+++ b/docs/architecture/grok-subscription-transport-contract.md
@@ -195,6 +195,30 @@ For both providers, a stream counts as a completion only when it ends with
- `error`,
- `unknown` with partial text or tool calls.
+## Errors
+
+Stable codes: `insufficient_scope`, `no_grant`, `model_not_allowed`,
+`budget_denied`, `connection_unavailable`, `provider_unavailable`,
+`origin_denied`, `ticket_invalid`, `ticket_replayed`, `request_hash_mismatch`,
+`client_upgrade_required`, `tool_call_limit_exceeded`.
+
+- `tool_call_limit_exceeded`: the upstream response carried more than
+ `maxToolCalls` tool calls. The proxy returns HTTP 422 with
+ `details: { limit, observed }`, or an SSE error frame when text had already
+ been streamed — the branch is decided by whether a frame reached the wire,
+ since tool-call frames are buffered until the stream completes. The Host maps
+ it to `LLM_TOOL_CALL_LIMIT_EXCEEDED`. It is not retryable and not
+ failover-eligible (failover class `null`), so the task fails with that code
+ instead of `LLM_MODEL_OVERLOADED`.
+- `request_limit_exceeded` (Host-side only): the request history exceeds
+ `maxMessages`. The Host raises it before authorization and maps it to
+ `LLM_CONTEXT_LENGTH_EXCEEDED`, not retryable.
+
+`grok_proxy_attempt_failures_total{code}` counts failed attempts. Its label is
+restricted to the codes above; anything else is recorded as `other`, because a
+control-api error body is not bounded by the proxy. The raw code stays in the
+`grok_proxy_attempt_finished` log line.
+
## Feature flags
All flags default to off.
diff --git a/packages/grok-provider-attempt-contract/index.cjs b/packages/grok-provider-attempt-contract/index.cjs
index 42e6d7ebb..1f5c69a29 100644
--- a/packages/grok-provider-attempt-contract/index.cjs
+++ b/packages/grok-provider-attempt-contract/index.cjs
@@ -19,7 +19,8 @@ const CATALOG_ORIGIN = 'https://cli-chat-proxy.grok.com/v1/models'
const LIMITS = Object.freeze({
maxRequestBodyBytes: 1048576,
maxMessages: 128,
- // Grok's Responses tool list is larger than Codex's 32.
+ // Independent of Codex, which is 256 since fba84cb34. Exceeding this is
+ // reported as `tool_call_limit_exceeded`, not as a provider outage.
maxToolCalls: 64,
maxOutputTokens: 16384,
maxDeadlineMs: 300000,