Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
docs(codex): document the contract limit refusal taxonomy (#731)
Alfredo Lopez3ffe082a1146
diff --git a/docs/architecture/codex-subscription-transport-contract.md b/docs/architecture/codex-subscription-transport-contract.mdindex 4bc6e77be..939952a4e 100644--- a/docs/architecture/codex-subscription-transport-contract.md+++ b/docs/architecture/codex-subscription-transport-contract.md@@ -247,9 +247,29 @@ Stable codes: `insufficient_scope`, `no_grant`, `model_not_allowed`,`LLM_TOOL_CALL_LIMIT_EXCEEDED`. It is not retryable and notfailover-eligible (failover class `null`), so the task fails with that codeinstead 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.+- `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+ 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+ `{ ok, code, message }` and nothing else:++ | Refusal message | Guard |+ | --------------------------------------------------- | ---------------------------- |+ | `request exceeds maxRequestBodyBytes` | serialized UTF-8 byte cap |+ | `request exceeds maxRequestBodyBytes element bound` | element count in `checkStructure` |+ | `messages exceed <maxMessages>` | message count |+ | `messages[i].toolCalls exceed <maxToolCalls>` | tool calls on one message |++ The element bound is named distinctly from the byte cap because the two have+ different remedies and a user report of the shared wording could not tell+ them apart. The contract's remaining `limit` refusals — nesting depth,+ `generation.maxOutputTokens` and `deadlineMs` out of range — stay+ `invalid_request`: a shorter conversation fixes none of them, and labelling+ them a context-length failure would invite a compaction loop that cannot+ converge.## Evidence