Skip to content

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

TypeScript

docs(llm): correct the rate-limit and control-plane comments (#720)

Alfredo Lopez1fa9dc5014ca
diff --git a/codex-llm-proxy/src/codexTransport.ts b/codex-llm-proxy/src/codexTransport.ts
index ddfbf6088..40a1adccb 100644
--- a/codex-llm-proxy/src/codexTransport.ts
+++ b/codex-llm-proxy/src/codexTransport.ts
@@ -420,6 +420,9 @@ async function dispatchUpstreamStream(
// G1-1 (#720): Retry-After is forwarded only as whole seconds in 1..3600, the
// rule mcp-host's gfsClient applies. An HTTP date or any other value is absent.
+// mcp-host parses what this forwards with its own copy of the rule
+// (`retryAfterMs` in mcp-host/src/llm/retryAfter.ts), and the Grok proxy has a
+// third (#799); a change here goes to both, or the Host drops the retry.
const MAX_RETRY_AFTER_SECONDS = 3600
function retryAfterSeconds(response: Response): number | undefined {
diff --git a/grok-llm-proxy/src/grokTransport.ts b/grok-llm-proxy/src/grokTransport.ts
index eb6a44515..00e984dc2 100644
--- a/grok-llm-proxy/src/grokTransport.ts
+++ b/grok-llm-proxy/src/grokTransport.ts
@@ -460,6 +460,9 @@ async function dispatchUpstreamStream(
// G1-1 (#720): Retry-After is forwarded only as whole seconds in 1..3600, the
// rule mcp-host's gfsClient applies. An HTTP date or any other value is absent.
+// mcp-host parses what this forwards with its own copy of the rule
+// (`retryAfterMs` in mcp-host/src/llm/retryAfter.ts), and the Codex proxy has a
+// third (#799); a change here goes to both, or the Host drops the retry.
const MAX_RETRY_AFTER_SECONDS = 3600
function retryAfterSeconds(response: Response): number | undefined {
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 30e327790..9df8f174f 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.456",
+ "version": "0.1.457",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.456",
+ "version": "0.1.457",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@anthropic-ai/sdk": "^0.32.0",
diff --git a/mcp-host/package.json b/mcp-host/package.json
index 5730a96ea..73cacef6e 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.456",
+ "version": "0.1.457",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/core/errors.ts b/mcp-host/src/core/errors.ts
index fb7ed98b6..58d373867 100644
--- a/mcp-host/src/core/errors.ts
+++ b/mcp-host/src/core/errors.ts
@@ -32,10 +32,14 @@ export enum LlmErrorCode {
AuthenticationFailed = 'LLM_AUTHENTICATION_FAILED',
ModelOverloaded = 'LLM_MODEL_OVERLOADED',
/**
- * Issue #720 — a control-plane hop no live process answered: a refused or
- * unresolvable connection to the authorize gateway or a subscription proxy,
- * or a gateway's own 502 in front of control-api. Retryable, with the
- * failover class `provider_unavailable`; only the label differs from
+ * Issue #720 — no control-plane process answered one hop of a subscription
+ * turn. mcp-host sets it from the JSON code `control_plane_unavailable`,
+ * never from an HTTP status. That code comes from a connect-phase failure
+ * (refused, unresolvable or timed-out connect) to the authorize gateway or a
+ * subscription proxy, from a proxy that could not reach control-api on
+ * redeem, or from the 503 JSON body the authorize and rpc gateways answer in
+ * place of their own 502. Retryable, with the failover class
+ * `provider_unavailable`; only the label differs from
* {@link LlmErrorCode.ModelOverloaded}.
*/
ControlPlaneUnavailable = 'LLM_CONTROL_PLANE_UNAVAILABLE',
diff --git a/mcp-host/src/llm/codexLlmProxyClient.ts b/mcp-host/src/llm/codexLlmProxyClient.ts
index 6b681f60d..94660686d 100644
--- a/mcp-host/src/llm/codexLlmProxyClient.ts
+++ b/mcp-host/src/llm/codexLlmProxyClient.ts
@@ -163,9 +163,10 @@ export class CodexLlmProxyClient {
return this.streamOnce(input, false)
}
const payload = (await response.json().catch(() => ({}))) as Record<string, unknown>
- // A 429 is a rate limit, not a provider outage (G1-6, G1-11, #720): a
- // limiter in front of the proxy may answer no JSON or a reason phrase,
- // so only a machine code a 429 carries replaces `rate_limited`.
+ // A 429 is a rate limit, not a provider outage (G1-6, G1-11, #720): the
+ // proxy answers `rate_limited` itself, and a 429 with no JSON code or a
+ // reason phrase is read the same way, so only a machine code a 429
+ // carries replaces `rate_limited`.
const code =
response.status === 413
? 'payload_too_large'
diff --git a/mcp-host/src/llm/failover/types.ts b/mcp-host/src/llm/failover/types.ts
index eff49ce35..db0c1bcfa 100644
--- a/mcp-host/src/llm/failover/types.ts
+++ b/mcp-host/src/llm/failover/types.ts
@@ -11,7 +11,8 @@
* The closed catalogue of error classes that may trigger a fallback (spec
* §3-R5.2). Defined as a mapping over the real `(LlmErrorCode, retryable)`
* tuples — `provider_unavailable` has no dedicated error code; it composes
- * `ModelOverloaded ∪ (ApiCallFailed ∧ retryable)`. See {@link classifyFailoverClass}.
+ * `ModelOverloaded ∪ ControlPlaneUnavailable ∪ (ApiCallFailed ∧ retryable)`.
+ * See {@link classifyFailoverClass}.
*/
export type FailoverClass = 'insufficient_quota' | 'auth' | 'provider_unavailable' | 'rate_limited'
diff --git a/mcp-host/src/llm/grokLlmProxyClient.ts b/mcp-host/src/llm/grokLlmProxyClient.ts
index 6994e5e64..c74595d47 100644
--- a/mcp-host/src/llm/grokLlmProxyClient.ts
+++ b/mcp-host/src/llm/grokLlmProxyClient.ts
@@ -151,9 +151,9 @@ export class GrokLlmProxyClient {
// A 413 with no JSON code comes from the gateway in front of the proxy
// (nginx `client_max_body_size`): a size refusal of this request, never a
// provider outage (#739). A code the 413 carries still wins. A 429 is a
- // rate limit (G1-6, G1-11, #720): a limiter may answer no JSON or a
- // reason phrase, so only a machine code a 429 carries replaces
- // `rate_limited`.
+ // rate limit (G1-6, G1-11, #720): the proxy answers `rate_limited`
+ // itself, and a 429 with no JSON code or a reason phrase is read the same
+ // way, so only a machine code a 429 carries replaces `rate_limited`.
const code =
response.status === 429
? rateLimitedCode(payload.error)
diff --git a/mcp-host/src/llm/providerAttemptAuthorizer.ts b/mcp-host/src/llm/providerAttemptAuthorizer.ts
index 160caba40..a43074aaa 100644
--- a/mcp-host/src/llm/providerAttemptAuthorizer.ts
+++ b/mcp-host/src/llm/providerAttemptAuthorizer.ts
@@ -151,9 +151,10 @@ export class ProviderAttemptAuthorizer {
// (#731): control-api answers `payload_too_large`, and the gateway in
// front of it (nginx `client_max_body_size`) answers with no JSON code.
// A 429 is a rate limit, not a provider outage (G1-6, G1-11, #720):
- // control-api's own authorize limiters answer a reason phrase and a
- // gateway limiter answers no JSON, so only a machine code a 429 carries
- // replaces `rate_limited`.
+ // control-api's own authorize limiters answer the reason phrase
+ // `Too Many Requests`, so only a machine code a 429 carries (such as
+ // `budget_denied`) replaces `rate_limited`; a 429 with no JSON code is
+ // `rate_limited` too.
const code =
response.status === 413
? 'payload_too_large'
diff --git a/mcp-host/src/llm/retryAfter.ts b/mcp-host/src/llm/retryAfter.ts
index 241d69fa2..a6088fc63 100644
--- a/mcp-host/src/llm/retryAfter.ts
+++ b/mcp-host/src/llm/retryAfter.ts
@@ -13,8 +13,8 @@ const MACHINE_CODE = /^[a-z][a-z0-9_]*$/
/**
* The code of a 429 (G1-11, #720): the machine code its JSON `error` carries
* (`rate_limited`, `budget_denied`, …), else `rate_limited`. control-api's own
- * limiters answer `{ "error": "Too Many Requests" }`, a reason phrase, and a
- * gateway limiter answers no JSON at all; both are a rate limit.
+ * limiters answer `{ "error": "Too Many Requests" }`, a reason phrase, which is
+ * a rate limit; so is a 429 with no JSON code at all.
*/
export function rateLimitedCode(error: unknown): string {
return typeof error === 'string' && MACHINE_CODE.test(error) ? error : 'rate_limited'