Skip to content

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

TypeScript

docs(transport): correct element classification, close-backstop comments and contract kind docs

Alfredo Lopez2a1ff2c313ae
diff --git a/codex-llm-proxy/src/server.ts b/codex-llm-proxy/src/server.ts
index 5232c4563..f96d91823 100644
--- a/codex-llm-proxy/src/server.ts
+++ b/codex-llm-proxy/src/server.ts
@@ -441,15 +441,15 @@ export function createProxyApps(
}, bodyReadDeadlineMs)
res.once('close', () => {
clearTimeout(readDeadline)
- // Backstop only while the slot is still held here. Once the handler
- // takes ownership it clears `req.codexStreamRelease` (hand-off) or the
- // demotion path releases it through `releaseAdmission`; in both cases
- // the handler's own `finally` frees the slot when it finishes
- // unwinding. Releasing here after hand-off would free the visual slot
- // and the principal share while the handler still holds the parsed
- // body during its (up to ~30 s) unwind, admitting another large body
- // over the gate width. Guarding on the field preserves the
- // `d5826f385` demotion fix (that path never runs this hook).
+ // Backstop only while the admission is still held here. A kept
+ // visual body transfers `req.codexStreamRelease` into the handler,
+ // which clears the field and releases in its outer `finally`. A
+ // demoted body releases through `releaseAdmission` before it joins
+ // the ordinary stream gate; this hook may still fire after demotion
+ // but finds the field empty and no-ops. Releasing here after hand-off
+ // would free the visual slot and the principal share while the
+ // handler still holds the parsed body during its (up to ~30 s)
+ // unwind, admitting another large body over the gate width.
if (req.codexStreamRelease) releaseVisual()
})
visualJson(req, res, err => {
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index 8e97d3837..7ef3d48ad 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.651",
+ "version": "0.1.652",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.651",
+ "version": "0.1.652",
"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 2cdde3af5..74a6b4932 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.651",
+ "version": "0.1.652",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/test/services.llmProviderAttemptAuthorizer.depth.test.ts b/control-api/test/services.llmProviderAttemptAuthorizer.depth.test.ts
index 08731eacd..ed5e81864 100644
--- a/control-api/test/services.llmProviderAttemptAuthorizer.depth.test.ts
+++ b/control-api/test/services.llmProviderAttemptAuthorizer.depth.test.ts
@@ -87,19 +87,6 @@ describe('authorizeLlmProviderAttempt nesting depth guard', () => {
for (const depth of [5000, 150000]) {
it(`rejects a ${depth}-deep ${p.provider} request with invalid_request, not a RangeError`, async () => {
const body = wireBody(p, nestedArrays(depth))
- // Exercising serialization at this depth proves the fixture reaches
- // the scanner. Whether V8's JSON.stringify overflows the stack at
- // exactly this depth is platform-dependent; the depth guard below is
- // the platform-independent contract.
- if (depth === 150000) {
- try {
- JSON.stringify(body)
- } catch {
- // A RangeError here confirms the fixture exceeds serializer
- // limits; completing without an error is equally acceptable on
- // runtimes with deeper native stacks.
- }
- }
const current = deps()
const attempt = authorizeLlmProviderAttempt(claims(p.scope), body, current)
await expect(attempt).rejects.toBeInstanceOf(LlmProviderAttemptAuthorizeError)
diff --git a/docs/architecture/grok-subscription-transport-contract.md b/docs/architecture/grok-subscription-transport-contract.md
index 5b727d1ee..0d4418610 100644
--- a/docs/architecture/grok-subscription-transport-contract.md
+++ b/docs/architecture/grok-subscription-transport-contract.md
@@ -363,8 +363,9 @@ the proxy both surface a size refusal (`kind: 'size'`) as HTTP 413
before it), while the Host raises `request_limit_exceeded` before it
authorizes at all — for the five size refusals listed under that code below —
`attachment_too_large` for the image budget refusals (classified as
-`InvalidAttachment`), `payload_too_large` for the container, member and
-element bounds (classified as `ContextLengthExceeded`), and
+`InvalidAttachment`), `request_limit_exceeded` for the element bound and
+`payload_too_large` for the container and member bounds (all three
+classified as `ContextLengthExceeded`), and
`invalid_request` for the rest, which no amount of compaction would fix.
That symmetry holds for a request and not for a response, which is why the
diff --git a/grok-llm-proxy/src/server.ts b/grok-llm-proxy/src/server.ts
index 68ba8a417..f9f3da16b 100644
--- a/grok-llm-proxy/src/server.ts
+++ b/grok-llm-proxy/src/server.ts
@@ -477,15 +477,15 @@ export function createProxyApps(
}, bodyReadDeadlineMs)
res.once('close', () => {
clearTimeout(readDeadline)
- // Backstop only while the slot is still held here. Once the handler
- // takes ownership it clears `req.grokStreamRelease` (hand-off) or the
- // demotion path releases it through `releaseAdmission`; in both cases
- // the handler's own `finally` frees the slot when it finishes
- // unwinding. Releasing here after hand-off would free the visual slot
- // and the principal share while the handler still holds the parsed
- // body during its (up to ~30 s) unwind, admitting another large body
- // over the gate width. Guarding on the field preserves the
- // `d5826f385` demotion fix (that path never runs this hook).
+ // Backstop only while the admission is still held here. A kept
+ // visual body transfers `req.grokStreamRelease` into the handler,
+ // which clears the field and releases in its outer `finally`. A
+ // demoted body releases through `releaseAdmission` before it joins
+ // the ordinary stream gate; this hook may still fire after demotion
+ // but finds the field empty and no-ops. Releasing here after hand-off
+ // would free the visual slot and the principal share while the
+ // handler still holds the parsed body during its (up to ~30 s)
+ // unwind, admitting another large body over the gate width.
if (req.grokStreamRelease) releaseVisual()
})
visualJson(req, res, err => {
diff --git a/packages/grok-provider-attempt-contract/index.cjs b/packages/grok-provider-attempt-contract/index.cjs
index 2bbaaa81c..c871b08be 100644
--- a/packages/grok-provider-attempt-contract/index.cjs
+++ b/packages/grok-provider-attempt-contract/index.cjs
@@ -201,8 +201,10 @@ const USAGE_KEYS = new Set(['inputTokens', 'outputTokens'])
// `kind` classifies a `limit` failure. The proxy and control-api answer
// `kind: 'size'` with payload_too_large and every other failure with
-// invalid_request, so `size` is set only where a byte budget refused. The V2
-// image count sets `count`; the other count and range bounds carry no kind.
+// invalid_request. `size` covers the byte budget and the aggregate structural
+// counts (containers, members, elements) that a shorter conversation can fix.
+// The V2 image count sets `count`; depth and other range bounds carry no kind
+// because compaction cannot fix them.
function fail(code, message, kind) {
return kind ? { ok: false, code, message, kind } : { ok: false, code, message }
}
diff --git a/packages/grok-provider-attempt-contract/index.d.ts b/packages/grok-provider-attempt-contract/index.d.ts
index 5b97f4685..41a758612 100644
--- a/packages/grok-provider-attempt-contract/index.d.ts
+++ b/packages/grok-provider-attempt-contract/index.d.ts
@@ -109,7 +109,8 @@ export declare const GROK_VISUAL_LIMITS: {
}
/**
- * `size`: a byte budget refused (payload_too_large). `count`: the V2 image
+ * `size`: a byte budget or aggregate structural count refused
+ * (payload_too_large). `count`: the V2 image
* count refused. Every other failure carries no kind.
*/
export type ContractLimitKind = 'size' | 'count'