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.jsonindex 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.jsonindex 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.tsindex 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 allowdiff --git a/docs/architecture/codex-subscription-transport-contract.md b/docs/architecture/codex-subscription-transport-contract.mdindex 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 belowthe 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. Theretained path parses one body at a time and queues at most two, in FIFOorder, 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 recipetarget. The allowed providers come only from the spec's model, alloweddiff --git a/docs/architecture/grok-subscription-transport-contract.md b/docs/architecture/grok-subscription-transport-contract.mdindex 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+ FIFOorder, paused before any read. One principal (JWT `sub` plus its sorted`hostRefs`) holds at most two positions, running or queued. A waiter isrefused 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 errorbody 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