Skip to content

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

TypeScript

docs(subscription): correct proxy refusal codes and the declared-length split

Alfredo Lopez886992f43c94
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index 5ad5a6c01..e4e0ab292 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.722",
+ "version": "0.1.723",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.722",
+ "version": "0.1.723",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/grok-provider-attempt-contract": "file:../packages/grok-provider-attempt-contract",
diff --git a/control-api/package.json b/control-api/package.json
index 68c864d42..896900c13 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.722",
+ "version": "0.1.723",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/middleware/llmProviderAttemptAdmissionLimits.ts b/control-api/src/middleware/llmProviderAttemptAdmissionLimits.ts
index d8b45dd29..62a161817 100644
--- a/control-api/src/middleware/llmProviderAttemptAdmissionLimits.ts
+++ b/control-api/src/middleware/llmProviderAttemptAdmissionLimits.ts
@@ -6,8 +6,12 @@ import type { AuthorizeBodyAdmissionPolicy } from './llmProviderAttemptBodyAdmis
// The policy is process-wide; every Node worker needs its own measured budget.
//
// It governs only the retained path: bodies declared above the text authorize
-// envelope, chunked bodies and unparseable lengths. Text-only authorizes are
-// bounded by their own parser limit and never take a unit (see the route).
+// envelope, chunked bodies and unparseable lengths. Bodies declared at or below
+// the envelope are bounded by their own parser limit and never take a unit (see
+// the route). The split is by declared length, not by content: a V2 text-only
+// body carries each text part twice (content and contentParts) and can exceed
+// the envelope while inside the non-image budget; it then takes the unit like
+// an image body.
//
// maxQueued, maxPerPrincipal and queueWaitMs bound latency and fairness, not
// memory: queued requests are paused before any body read. Two waiters allow
diff --git a/docs/architecture/codex-subscription-transport-contract.md b/docs/architecture/codex-subscription-transport-contract.md
index dac94d272..9f9c5e6d2 100644
--- a/docs/architecture/codex-subscription-transport-contract.md
+++ b/docs/architecture/codex-subscription-transport-contract.md
@@ -137,7 +137,10 @@ request whose declared `Content-Length` is at or below
the text authorize envelope (`maxRequestBodyBytes` +
`ENVELOPE_ALLOWANCE_BYTES`, 8404992 bytes, the larger of the two contracts)
is parsed with that limit and never queues. A larger declared length, a
-chunked body or a length that is not plain digits takes the unit. The
+chunked body or a length that is not plain digits takes the unit. The split is
+by declared length, not by content: a V2 text-only body carries each text part
+twice (`content` and `contentParts`), so it can exceed the envelope while inside
+the non-image budget, and it then takes the unit like an image body. The
retained path parses one body at a time and queues at most two, in FIFO
order, paused before any read. One principal (JWT `sub` plus its sorted
`hostRefs`) holds at most two positions, running or queued. A waiter is
@@ -587,11 +590,18 @@ behavior changes:
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}`.
- A request the proxy refuses on its own request limits (stream queue full,
- queue wait exceeded, invalid deadline) reaches the Host as
- `provider_unavailable`. The metric labels it `request_limit` to keep it
- apart from upstream outages, and the log line carries the limit's fixed
- `reason`.
+ A request the proxy refuses on its own request limits reaches the Host
+ with a proxy-owned code. A full or waited-out ordinary stream queue, or a
+ full body-admission queue, answers 503 `proxy_capacity_exceeded`. A full
+ or waited-out visual queue answers 503 `visual_gate`, and a full principal
+ share answers 503 `visual_host_share`. An invalid deadline, a caller
+ deadline that ends the wait first, a body-admission wait cut by the
+ admission deadline and a wait cut by the ticket's expiry keep 503
+ `provider_unavailable`. The attempt-failure metric labels refusals inside
+ the completion handler `request_limit` (ticket expiry excepted), to keep
+ them apart from upstream outages. Admission refusals are logged as
+ `codex_proxy_admission_refused` with a fixed `reason` (`body_budget`,
+ `visual_host_share`, `visual_gate`, `ticket_life`).
- **Live-target attestation.** Codex authorize attests the live Host or recipe
target. The allowed providers come only from the spec's model, allowed
diff --git a/docs/architecture/grok-subscription-transport-contract.md b/docs/architecture/grok-subscription-transport-contract.md
index f3147111d..1433804db 100644
--- a/docs/architecture/grok-subscription-transport-contract.md
+++ b/docs/architecture/grok-subscription-transport-contract.md
@@ -261,8 +261,12 @@ Errors:
the text authorize envelope (`maxRequestBodyBytes` +
`ENVELOPE_ALLOWANCE_BYTES`, 8404992 bytes, the larger of the two contracts)
is parsed with that limit and never queues. A larger declared length, a
- chunked body or a length that is not plain digits takes the unit. The
- retained path parses one body at a time and queues at most two, in FIFO
+ chunked body or a length that is not plain digits takes the unit. The split
+ is by declared length, not by content: a V2 text-only body carries each text
+ part twice (`content` and `contentParts`), so it can exceed the envelope
+ while inside the non-image budget, and it then takes the unit like an image
+ body. The retained path parses one body at a time and queues at most two, in
+ FIFO
order, paused before any read. One principal (JWT `sub` plus its sorted
`hostRefs`) holds at most two positions, running or queued. A waiter is
refused after 40 s, the holder's read deadline (10 s) plus its work deadline
@@ -877,10 +881,18 @@ transport now raises it for a contract size refusal.
Anything outside the table 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.
-A request the proxy refuses on its own request limits (stream queue full,
-queue wait exceeded, invalid deadline) reaches the Host as
-`provider_unavailable`. The metric labels it `request_limit` to keep it apart
-from upstream outages, and the log line carries the limit's fixed `reason`.
+A request the proxy refuses on its own request limits reaches the Host with a
+proxy-owned code. A full or waited-out ordinary stream queue, or a full
+body-admission queue, answers 503 `proxy_capacity_exceeded`. A full or
+waited-out visual queue answers 503 `visual_gate`, and a full principal share
+answers 503 `visual_host_share`. An invalid deadline, a caller deadline that
+ends the wait first, a body-admission wait cut by the admission deadline and a
+wait cut by the ticket's expiry keep 503 `provider_unavailable`. The
+attempt-failure metric labels refusals inside the completion handler
+`request_limit` (ticket expiry excepted), to keep them apart from upstream
+outages. Admission refusals are logged as `grok_proxy_admission_refused` with
+a fixed `reason` (`body_budget`, `visual_host_share`, `visual_gate`,
+`ticket_life`).
### Control-plane outage