Skip to content

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

TypeScript

docs(codex): document the 64/256 limits, tool_call_limit_exceeded and attempt telemetry

Alfredo Lopez4ec5a456275b
diff --git a/docs/architecture/codex-subscription-transport-contract.md b/docs/architecture/codex-subscription-transport-contract.md
index c22645472..7fcb3d8a1 100644
--- a/docs/architecture/codex-subscription-transport-contract.md
+++ b/docs/architecture/codex-subscription-transport-contract.md
@@ -52,8 +52,8 @@ one physical execution per ticket. A retry or fallback must mint a new attempt.
| Limit | Value |
| -------------------- | ------- |
| maxRequestBodyBytes | 1048576 |
-| maxMessages | 128 |
-| maxToolCalls | 32 |
+| maxMessages | 256 |
+| maxToolCalls | 64 |
| maxOutputTokens | 16384 |
| maxStreamDurationMs | 300000 |
| maxDeadlineMs | 300000 |
@@ -64,9 +64,16 @@ 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
-name, schema, finite-value and unknown-field validation. `maxToolCalls` bounds
-calls in each assistant history message and each newly returned response. The proxy buffers tool calls until successful completion and validates the bound before publishing any executable call; the Host validates it again before returning the batch. It is not a catalog size limit and
-does not widen execution concurrency. This preserves the existing call bound.
+name, schema, finite-value and unknown-field validation. `maxToolCalls` (64)
+bounds calls in each assistant history message and each newly returned
+response. The proxy buffers tool calls until successful completion and
+validates the bound before publishing any executable call; the Host validates
+it again before returning the batch. A response over the bound fails with
+`tool_call_limit_exceeded`, which is not retried and does not fail over. It is
+not a catalog size limit and does not widen execution concurrency.
+`maxMessages` (256) bounds the request history. The Host rejects a longer
+history with `request_limit_exceeded` before authorization, so no ticket is
+minted for it.
The former `maxTools: 32` definition limit was imposed by Evenfire, not a
verified Codex Subscription limit. Remote endpoint limits remain separately
@@ -191,6 +198,22 @@ behavior changes:
- It drops queued stream-gate waiters on abort and checks the abort signal
before redeeming a ticket.
- It requires `maxStreamDurationMs` greater than 0.
+ - It logs one `codex_proxy_attempt_finished` event per completion attempt,
+ with identifiers and counts only (never the body, ticket, frames, tool
+ names or arguments): `providerAttemptId`, `hostRef`, `model`,
+ `requestHash`, `outcome`, `deliveredAs`, `toolCalls`, `textChunks` and
+ `durationMs`. On a stream that reached the upstream's terminal frame,
+ `outcome` is `success`, `canceled`, `error` or `unknown`, with
+ `deliveredAs: 'sse_done'` and `usage` when present. On a thrown failure,
+ `outcome` is `failed` and the event adds `code`, the transport `reason`,
+ `details` (for example `{limit, observed}` on
+ `tool_call_limit_exceeded`) and `deliveredAs`: `http_status` with
+ `httpStatus` when no SSE byte had been sent, or `sse_error` when the
+ failure went out as an SSE error frame.
+ - Do not confuse the two `outcome` fields. The finalize receipt sent to
+ control-api keeps `success | canceled | error | unknown`. Only the
+ `codex_proxy_attempt_finished` log line adds `failed`.
+ - It counts failed attempts in `codex_proxy_attempt_failures_total{code}`.
- **Live-target attestation.** Codex authorize attests the live Host or recipe
target. The allowed providers come only from the spec's model, allowed
models and fallbacks (Hosts) or agent providers (recipes). A target that
@@ -215,7 +238,18 @@ behavior changes:
Stable codes: `insufficient_scope`, `no_grant`, `model_not_allowed`,
`budget_denied`, `connection_unavailable`, `provider_unavailable`,
-`origin_denied`, `ticket_invalid`, `ticket_replayed`, `request_hash_mismatch`.
+`origin_denied`, `ticket_invalid`, `ticket_replayed`, `request_hash_mismatch`,
+`tool_call_limit_exceeded`.
+
+- `tool_call_limit_exceeded`: the upstream response carried more than
+ `maxToolCalls` tool calls. The proxy returns HTTP 422, or an SSE error frame
+ when text had already been streamed. 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.
## Evidence
diff --git a/docs/architecture/grok-subscription-transport-contract.md b/docs/architecture/grok-subscription-transport-contract.md
index c512e963d..4612e5e55 100644
--- a/docs/architecture/grok-subscription-transport-contract.md
+++ b/docs/architecture/grok-subscription-transport-contract.md
@@ -121,7 +121,7 @@ an error.
## Limits
Owned by `@clerum/grok-provider-attempt-contract`. Independent of Codex
-`LIMITS` (`maxToolCalls` is 64, not 32).
+`LIMITS` (`maxToolCalls` is 64 for both contracts; `maxMessages` is 128 for Grok, 256 for Codex).
Proxy robustness (both proxies):
diff --git a/tests/e2e/fixtures/codex-subscription/sanitized-upstream-contract.json b/tests/e2e/fixtures/codex-subscription/sanitized-upstream-contract.json
index c91e01896..380ef194f 100644
--- a/tests/e2e/fixtures/codex-subscription/sanitized-upstream-contract.json
+++ b/tests/e2e/fixtures/codex-subscription/sanitized-upstream-contract.json
@@ -41,8 +41,8 @@
"oauthScopes": ["openid", "profile", "email", "offline_access"],
"limits": {
"maxRequestBodyBytes": 1048576,
- "maxMessages": 128,
- "maxToolCalls": 32,
+ "maxMessages": 256,
+ "maxToolCalls": 64,
"maxOutputTokens": 16384,
"maxStreamDurationMs": 300000,
"maxDeadlineMs": 300000,
@@ -60,7 +60,8 @@
"origin_denied",
"ticket_invalid",
"ticket_replayed",
- "request_hash_mismatch"
+ "request_hash_mismatch",
+ "tool_call_limit_exceeded"
],
"termsAndTestAccount": {
"automationAuthorized": true,
diff --git a/tests/e2e/fixtures/package-lock.json b/tests/e2e/fixtures/package-lock.json
index ed3798c84..0d1f39505 100644
--- a/tests/e2e/fixtures/package-lock.json
+++ b/tests/e2e/fixtures/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "@clerum/e2e-test-fixtures",
- "version": "1.0.82",
+ "version": "1.0.83",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@clerum/e2e-test-fixtures",
- "version": "1.0.82",
+ "version": "1.0.83",
"dependencies": {
"@kubernetes/client-node": "^1.0.0"
},
diff --git a/tests/e2e/fixtures/package.json b/tests/e2e/fixtures/package.json
index 4a7bd3ce9..e99436a70 100644
--- a/tests/e2e/fixtures/package.json
+++ b/tests/e2e/fixtures/package.json
@@ -1,6 +1,6 @@
{
"name": "@clerum/e2e-test-fixtures",
- "version": "1.0.82",
+ "version": "1.0.83",
"description": "E2E test fixtures and utilities for Clerum testing",
"type": "module",
"main": "index.ts",
diff --git a/tests/e2e/integration/codex-subscription-contract-freeze.test.ts b/tests/e2e/integration/codex-subscription-contract-freeze.test.ts
index 7fb0df179..d72396e5f 100644
--- a/tests/e2e/integration/codex-subscription-contract-freeze.test.ts
+++ b/tests/e2e/integration/codex-subscription-contract-freeze.test.ts
@@ -154,7 +154,8 @@ describe('codex-subscription contract freeze', () => {
}
expect(limits).not.toHaveProperty('maxTools')
- expect(limits?.maxToolCalls).toBe(32)
+ expect(limits?.maxToolCalls).toBe(64)
+ expect(limits?.maxMessages).toBe(256)
expect(limits?.maxRequestBodyBytes).toBe(1048576)
const errors = contract.errorTaxonomy
@@ -163,6 +164,7 @@ describe('codex-subscription contract freeze', () => {
expect(typeof code).toBe('string')
expect(String(code)).toMatch(/^[a-z][a-z0-9_]+$/)
}
+ expect(errors).toContain('tool_call_limit_exceeded')
const terms = contract.termsAndTestAccount as Record<string, unknown> | undefined
expect(terms && typeof terms === 'object').toBe(true)
diff --git a/tests/e2e/package-lock.json b/tests/e2e/package-lock.json
index 7d7aecf0b..35fedd54d 100644
--- a/tests/e2e/package-lock.json
+++ b/tests/e2e/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-e2e-tests",
- "version": "0.1.83",
+ "version": "0.1.84",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-e2e-tests",
- "version": "0.1.83",
+ "version": "0.1.84",
"devDependencies": {
"@types/jsonwebtoken": "^9.0.10",
"@types/node": "^22.0.0",
diff --git a/tests/e2e/package.json b/tests/e2e/package.json
index aad2a7b47..5291367a7 100644
--- a/tests/e2e/package.json
+++ b/tests/e2e/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-e2e-tests",
- "version": "0.1.83",
+ "version": "0.1.84",
"private": true,
"type": "module",
"scripts": {