Skip to content

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

TypeScript

fix(sdk): restore the per-grant output ceiling and close the R4 residuals

Alfredo Lopezec27eef66816
diff --git a/charts/clerum-crds/crds/workflowrecipe.yaml b/charts/clerum-crds/crds/workflowrecipe.yaml
index 741b54c2f..082826e5f 100644
--- a/charts/clerum-crds/crds/workflowrecipe.yaml
+++ b/charts/clerum-crds/crds/workflowrecipe.yaml
@@ -478,13 +478,15 @@ spec:
type: integer
minimum: 1
description: >-
- DEPRECATED — accepted for
- compatibility but no longer enforced.
- The Codex ChatGPT wire discards
- max_output_tokens, so no layer capped
- the response by token count.
- Scheduled for removal in a future
- version.
+ Per-grant output ceiling. Enforced
+ as max_tokens on API-key providers
+ (OpenAI, Claude, Z.AI, Bedrock,
+ Google). codex-subscription cannot
+ bind it: the ChatGPT wire rejects
+ max_output_tokens, so there it only
+ shapes the authorize request identity
+ and the enforced bound is the
+ contract limit of 16384.
clientNotifications:
type: object
required: [allowedEventTypes]
@@ -1720,11 +1722,13 @@ spec:
type: integer
minimum: 1
description: >-
- DEPRECATED — accepted for compatibility but no
- longer enforced. The Codex ChatGPT wire discards
- max_output_tokens, so no layer capped the response
- by token count. Scheduled for removal in a future
- version.
+ Per-grant output ceiling. Enforced as max_tokens
+ on API-key providers (OpenAI, Claude, Z.AI,
+ Bedrock, Google). codex-subscription cannot bind
+ it: the ChatGPT wire rejects max_output_tokens, so
+ there it only shapes the authorize request identity
+ and the enforced bound is the contract limit of
+ 16384.
maxRequestsPerRun:
type: integer
minimum: 1
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index 4d43f93f6..50524b19b 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.541",
+ "version": "0.1.542",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.541",
+ "version": "0.1.542",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/image-policy": "file:../packages/image-policy",
diff --git a/control-api/package.json b/control-api/package.json
index 7a1f768c4..20e5a7fea 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.541",
+ "version": "0.1.542",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/routes/admin/pluginWorkloadSdk.ts b/control-api/src/routes/admin/pluginWorkloadSdk.ts
index 833f20cf3..89b149045 100644
--- a/control-api/src/routes/admin/pluginWorkloadSdk.ts
+++ b/control-api/src/routes/admin/pluginWorkloadSdk.ts
@@ -148,21 +148,22 @@ function parseModelArray(value: unknown, field: string, res: Response): string[]
// wire for compatibility and are validated with the same shape rules, but they
// are stripped before persistence — only per-minute/platform limits are stored.
//
-// J8: `maxOutputTokens` joins them. It was advertised as a policy ceiling but
-// bound nothing: the Codex ChatGPT wire rejects `max_output_tokens`, so no
-// layer ever capped the response by token count. The only real bound is the
-// 300s wall clock, and the budget reservation is admission control that denies
-// the NEXT call, after the overspend already happened. Persisting the key kept
-// a promise the platform could not keep.
+// R4-H2: `maxOutputTokens` was briefly moved here on the premise that nothing
+// enforced it. That premise held only for codex-subscription, whose ChatGPT
+// wire rejects `max_output_tokens` and whose proxy therefore omits it. Every
+// API-key provider does send it (`openai.ts`, `bedrockConverse.ts`,
+// `googleGenerative.ts`), so for them it was a working per-grant billing
+// ceiling. The key is active again, with its real scope stated wherever an
+// operator can read it, rather than a ceiling silently ignored everywhere.
const DEPRECATED_QUOTA_LIMIT_KEYS: ReadonlyArray<keyof PluginWorkloadSdkQuotaLimits> = [
'maxRequestsPerRun',
'maxNotificationsPerRun',
- 'maxOutputTokens',
]
const ACTIVE_QUOTA_LIMIT_KEYS: ReadonlyArray<keyof PluginWorkloadSdkQuotaLimits> = [
'maxInvocationsPerMinute',
'maxNotificationsPerMinute',
+ 'maxOutputTokens',
]
function parseQuotaLimits(value: unknown, res: Response): PluginWorkloadSdkQuotaLimits | null {
diff --git a/control-api/src/services/pluginWorkloadSdkAuthorizer.ts b/control-api/src/services/pluginWorkloadSdkAuthorizer.ts
index be07334b5..3ed47a978 100644
--- a/control-api/src/services/pluginWorkloadSdkAuthorizer.ts
+++ b/control-api/src/services/pluginWorkloadSdkAuthorizer.ts
@@ -112,6 +112,12 @@ export interface AuthorizePromptBridgeParams {
}
export interface AuthorizedPromptBridge {
+ /**
+ * Per-grant output ceiling. Enforced as `max_tokens` on API-key providers;
+ * codex-subscription cannot bind it on the ChatGPT wire and is bounded by
+ * the contract's structural LIMITS.maxOutputTokens instead (R4-H2).
+ */
+ maxOutputTokens: number | null
invocationId: string
/** True when this idempotency key already produced an invocation. */
replay: boolean
@@ -397,6 +403,7 @@ async function authorizePromptBridgeInner(
attemptGeneration: recorded.invocation.attemptGeneration,
policyRevision: grant.policyRevision,
policyHash: resolvedPolicyHash,
+ maxOutputTokens: grant.quotaLimits.maxOutputTokens ?? null,
},
}
}
@@ -494,6 +501,7 @@ async function authorizePromptBridgeInner(
attemptGeneration: recorded.invocation.attemptGeneration,
policyRevision: grant.policyRevision,
policyHash: resolvedPolicyHash,
+ maxOutputTokens: grant.quotaLimits.maxOutputTokens ?? null,
},
}
}
diff --git a/control-api/test/routes.adminPluginWorkloadSdk.test.ts b/control-api/test/routes.adminPluginWorkloadSdk.test.ts
index 0a182f459..087604d12 100644
--- a/control-api/test/routes.adminPluginWorkloadSdk.test.ts
+++ b/control-api/test/routes.adminPluginWorkloadSdk.test.ts
@@ -536,9 +536,10 @@ describe('routes/admin/pluginWorkloadSdk — grants', () => {
// (malformed still 400s, pinned above) but are dropped on write, while the
// active per-minute keys persist untouched.
//
- // J8: maxOutputTokens joins the stripped set. It was persisted and
- // advertised as a policy ceiling, but the Codex ChatGPT wire discards
- // max_output_tokens, so nothing ever capped the response by token count.
+ // R4-H2: maxOutputTokens is NOT stripped. It briefly was, on the premise
+ // that nothing enforced it — true only for codex-subscription. Every
+ // API-key provider sends max_tokens, so for them it is a live per-grant
+ // billing ceiling and it must reach the grant.
vi.mocked(sdkDb.upsertGrant).mockResolvedValue({ id: 'g1' } as never)
const res = await request(buildApp())
.post('/admin/plugin-workload-sdk/grants')
@@ -554,16 +555,16 @@ describe('routes/admin/pluginWorkloadSdk — grants', () => {
expect(res.status).toBe(200)
expect(sdkDb.upsertGrant).toHaveBeenCalledWith(
expect.objectContaining({
- quotaLimits: { maxInvocationsPerMinute: 30 },
+ quotaLimits: { maxInvocationsPerMinute: 30, maxOutputTokens: 4096 },
}),
'11111111-1111-4111-8111-111111111111',
expect.anything() // carrier transaction client (R1-H3 fase 2)
)
})
- it('still shape-validates the deprecated maxOutputTokens on the wire (J8)', async () => {
- // Deprecating the key must not loosen the boundary: a malformed value is
- // still a 400, exactly as it was while the key was persisted.
+ it('rejects a malformed maxOutputTokens on the wire', async () => {
+ // A ceiling of 0 would clamp every response to nothing; it is a 400, not a
+ // silently ignored value.
const res = await request(buildApp())
.post('/admin/plugin-workload-sdk/grants')
.send({ ...validGrantBody, quotaLimits: { maxOutputTokens: 0 } })
diff --git a/control-api/test/services.pluginWorkloadSdkAuthorizer.test.ts b/control-api/test/services.pluginWorkloadSdkAuthorizer.test.ts
index 0b314e973..e6b6997ed 100644
--- a/control-api/test/services.pluginWorkloadSdkAuthorizer.test.ts
+++ b/control-api/test/services.pluginWorkloadSdkAuthorizer.test.ts
@@ -602,9 +602,11 @@ describe('authorizePromptBridge', () => {
value: { invocationId: 'inv-1', replay: false },
})
if (!result.ok) throw new Error('expected the authorization to succeed')
- // J8: a legacy grant may still carry maxOutputTokens, but the authorization
- // must not re-advertise it as a policy ceiling — nothing enforced it.
- expect(result.value).not.toHaveProperty('maxOutputTokens')
+ // R4-H2: the grant's output ceiling travels on the authorization again.
+ // J8 removed it on the premise that nothing enforced it, which held only
+ // for codex-subscription; every API-key provider sends it as `max_tokens`,
+ // so for them it was a working per-grant billing control.
+ expect(result.value.maxOutputTokens).toBe(2048)
expect(sdkDb.insertInvocation).toHaveBeenCalledOnce()
// Issue #348: the per-run leg is inert — no period quota is consumed even
// though the grant still carries a legacy maxRequestsPerRun value.
diff --git a/control-api/test/services.pluginWorkloadSdkSpend.properties.test.ts b/control-api/test/services.pluginWorkloadSdkSpend.properties.test.ts
new file mode 100644
index 000000000..3a997b713
--- /dev/null
+++ b/control-api/test/services.pluginWorkloadSdkSpend.properties.test.ts
@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'vitest'
+import fc from 'fast-check'
+import { deriveEffectiveSpend } from '../src/services/pluginWorkloadSdkFinalization.js'
+import { isOauthBrokerProvider } from '../src/services/pluginWorkloadSdkSpendLedger.js'
+
+/**
+ * R4-M2. `deriveEffectiveSpend` is a pure `(floor, linkedCodex) -> spend` merge
+ * with precedence rules, and it was covered only by hand-enumerated cases.
+ * R4-H1 and R4-M1 were both sibling cases that enumeration missed — the shape
+ * of that miss is what these properties close: they quantify over the whole
+ * input space instead of the examples someone thought of.
+ */
+
+const OUTCOMES = ['exact', 'unknown', 'not_executed'] as const
+const PROVIDERS = ['codex-subscription', 'openai', 'zai'] as const
+const LINKED_OUTCOMES = ['success', 'error', 'canceled', 'unknown'] as const
+
+/** A persisted floor row that always satisfies the table's token_pair_check. */
+const persistedArb = fc
+ .record({
+ provider: fc.constantFrom(...PROVIDERS),
+ outcome: fc.constantFrom(...OUTCOMES),
+ tokens: fc.tuple(fc.nat({ max: 100_000 }), fc.nat({ max: 100_000 })),
+ })
+ .map(({ provider, outcome, tokens }) => ({
+ provider,
+ outcome,
+ input_tokens: outcome === 'exact' ? tokens[0] : null,
+ output_tokens: outcome === 'exact' ? tokens[1] : null,
+ }))
+
+const linkedArb = fc.option(
+ fc.record({
+ outcome: fc.constantFrom(...LINKED_OUTCOMES),
+ usageInputTokens: fc.option(fc.nat({ max: 100_000 }), { nil: null }),
+ usageOutputTokens: fc.option(fc.nat({ max: 100_000 }), { nil: null }),
+ }),
+ { nil: null }
+)
+
+/** Round-trip a derived spend back into the row shape it would be read from. */
+function asRow(provider: string, spend: ReturnType<typeof deriveEffectiveSpend>) {
+ return {
+ provider,
+ outcome: spend.outcome,
+ input_tokens: spend.inputTokens,
+ output_tokens: spend.outputTokens,
+ }
+}
+
+describe('deriveEffectiveSpend properties', () => {
+ it('is terminal for exact and not_executed floors', () => {
+ fc.assert(
+ fc.property(persistedArb, linkedArb, (persisted, linked) => {
+ fc.pre(persisted.outcome !== 'unknown')
+ const derived = deriveEffectiveSpend(persisted, linked)
+ expect(derived.outcome).toBe(persisted.outcome)
+ if (persisted.outcome === 'exact') {
+ expect(derived.inputTokens).toBe(persisted.input_tokens)
+ expect(derived.outputTokens).toBe(persisted.output_tokens)
+ }
+ })
+ )
+ })
+
+ it('only ever lifts unknown, and only to exact backed by a complete token pair', () => {
+ fc.assert(
+ fc.property(persistedArb, linkedArb, (persisted, linked) => {
+ fc.pre(persisted.outcome === 'unknown')
+ const derived = deriveEffectiveSpend(persisted, linked)
+ expect(['unknown', 'exact']).toContain(derived.outcome)
+
+ const liftable =
+ isOauthBrokerProvider(persisted.provider) &&
+ linked?.outcome === 'success' &&
+ Number.isInteger(linked.usageInputTokens) &&
+ Number.isInteger(linked.usageOutputTokens)
+ expect(derived.outcome === 'exact').toBe(Boolean(liftable))
+ })
+ )
+ })
+
+ it('never derives anything for a non-oauth-broker provider', () => {
+ fc.assert(
+ fc.property(persistedArb, linkedArb, (persisted, linked) => {
+ fc.pre(!isOauthBrokerProvider(persisted.provider))
+ expect(deriveEffectiveSpend(persisted, linked).outcome).toBe(persisted.outcome)
+ })
+ )
+ })
+
+ it('is idempotent: deriving from an already-derived row changes nothing', () => {
+ fc.assert(
+ fc.property(persistedArb, linkedArb, (persisted, linked) => {
+ const once = deriveEffectiveSpend(persisted, linked)
+ const twice = deriveEffectiveSpend(asRow(persisted.provider, once), linked)
+ expect(twice).toEqual(once)
+ })
+ )
+ })
+
+ it('never fabricates a partial token pair', () => {
+ fc.assert(
+ fc.property(persistedArb, linkedArb, (persisted, linked) => {
+ const { outcome, inputTokens, outputTokens } = deriveEffectiveSpend(persisted, linked)
+ expect(outcome === 'exact').toBe(inputTokens !== null)
+ expect(inputTokens === null).toBe(outputTokens === null)
+ })
+ )
+ })
+})
diff --git a/control-ui/lib/api.ts b/control-ui/lib/api.ts
index 7b26a6c74..acb6bc7d2 100644
--- a/control-ui/lib/api.ts
+++ b/control-ui/lib/api.ts
@@ -3722,13 +3722,12 @@ export type PluginWorkloadSdkGrantInput = {
allowedTargetRefs?: string[]
allowedUserRefs?: string[]
allowedCallers?: string[]
- // Input type omits the deprecated keys (per-run: issue #348; maxOutputTokens:
- // J8): this UI never sends them and the server strips them on write. The
- // response PluginWorkloadSdkQuotaLimits still carries them for legacy grants.
- quotaLimits?: Omit<
- PluginWorkloadSdkQuotaLimits,
- 'maxRequestsPerRun' | 'maxNotificationsPerRun' | 'maxOutputTokens'
- >
+ // Input type omits the deprecated per-run keys (issue #348): this UI never
+ // sends them and the server strips them on write. The response
+ // PluginWorkloadSdkQuotaLimits still carries them for legacy grants.
+ // `maxOutputTokens` is NOT among them (R4-H2) — it is a live per-grant
+ // ceiling on API-key providers.
+ quotaLimits?: Omit<PluginWorkloadSdkQuotaLimits, 'maxRequestsPerRun' | 'maxNotificationsPerRun'>
modelPolicies?: Record<string, PluginWorkloadSdkModelPolicy>
promptTargets?: PluginWorkloadSdkPromptTarget[]
defaultTargetRef?: string
diff --git a/control-ui/package-lock.json b/control-ui/package-lock.json
index d93864f72..28b0f3e26 100644
--- a/control-ui/package-lock.json
+++ b/control-ui/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-ui",
- "version": "0.1.488",
+ "version": "0.1.489",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-ui",
- "version": "0.1.488",
+ "version": "0.1.489",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/llm-providers": "file:../packages/llm-providers",
diff --git a/control-ui/package.json b/control-ui/package.json
index 58d7b4e32..b8bc71069 100644
--- a/control-ui/package.json
+++ b/control-ui/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-ui",
- "version": "0.1.488",
+ "version": "0.1.489",
"private": true,
"scripts": {
"dev": "NEXT_IGNORE_INCORRECT_LOCKFILE=1 next dev",
diff --git a/desktop-app/test/e2e-playwright/plugin-workload-sdk-codex-fallback.spec.ts b/desktop-app/test/e2e-playwright/plugin-workload-sdk-codex-fallback.spec.ts
index 8eed48c30..539f699bf 100644
--- a/desktop-app/test/e2e-playwright/plugin-workload-sdk-codex-fallback.spec.ts
+++ b/desktop-app/test/e2e-playwright/plugin-workload-sdk-codex-fallback.spec.ts
@@ -8,6 +8,7 @@ import {
embeddedText,
findSandboxUiContents,
latestSdkInvocationStatus,
+ profilesNow,
promptBridgeAttemptsForRun,
promptBridgeGrantTargets,
readPluginWorkloadSdkStatus,
@@ -182,7 +183,7 @@ test('Desktop Apps falls back to the authorized non-Codex target when Codex is u
await expectProxyStopped()
})
- const runStartedAt = new Date().toISOString()
+ const runStartedAt = profilesNow()
const before = sdkInvocationCount(fixture, 'promptBridge')
await typeEmbedded(
app,
diff --git a/desktop-app/test/e2e-playwright/plugin-workload-sdk-no-grant-guard.spec.ts b/desktop-app/test/e2e-playwright/plugin-workload-sdk-no-grant-guard.spec.ts
index ef1a68bb0..27f4f6bf0 100644
--- a/desktop-app/test/e2e-playwright/plugin-workload-sdk-no-grant-guard.spec.ts
+++ b/desktop-app/test/e2e-playwright/plugin-workload-sdk-no-grant-guard.spec.ts
@@ -8,6 +8,7 @@ import {
embeddedText,
findSandboxUiContents,
latestSdkInvocationStatus,
+ profilesNow,
promptBridgeLedgerForRun,
readPluginWorkloadSdkStatus,
sandboxUiViewUrlPrefix,
@@ -149,7 +150,7 @@ test('Desktop Apps refuses a Codex prompt when the execution binding is missing'
})
.toContain(sandboxUiViewUrlPrefix(fixture))
const webContentsId = embedded!.id
- const runStartedAt = new Date().toISOString()
+ const runStartedAt = profilesNow()
const before = sdkInvocationCount(fixture, 'promptBridge')
await typeEmbedded(app, webContentsId, '#prompt', 'This prompt must not dispatch Codex.')
await activateEmbedded(app, webContentsId, '#run')
diff --git a/desktop-app/test/e2e-playwright/plugin-workload-sdk-sandbox-ui.spec.ts b/desktop-app/test/e2e-playwright/plugin-workload-sdk-sandbox-ui.spec.ts
index fb740c5d1..aa1dc4acb 100644
--- a/desktop-app/test/e2e-playwright/plugin-workload-sdk-sandbox-ui.spec.ts
+++ b/desktop-app/test/e2e-playwright/plugin-workload-sdk-sandbox-ui.spec.ts
@@ -15,6 +15,7 @@ import {
findSandboxUiContents,
latestSdkInvocationStatus,
notificationDeliverySignal,
+ profilesNow,
promptBridgeLedgerForRun,
readPluginWorkloadSdkStatus,
requireExpectedSdkProvider,
@@ -165,7 +166,7 @@ test('Desktop Apps executes promptBridge and clientNotifications inside the real
}
const marker = `desktop-sdk-${Date.now()}`
- const runStartedAt = new Date().toISOString()
+ const runStartedAt = profilesNow()
await test.step('reject an empty prompt without creating an invocation', async () => {
const before = sdkInvocationCount(fixture, 'promptBridge')
diff --git a/desktop-app/test/e2e-playwright/pluginWorkloadSdkSandboxUi.ts b/desktop-app/test/e2e-playwright/pluginWorkloadSdkSandboxUi.ts
index 14587e744..0e87cad0d 100644
--- a/desktop-app/test/e2e-playwright/pluginWorkloadSdkSandboxUi.ts
+++ b/desktop-app/test/e2e-playwright/pluginWorkloadSdkSandboxUi.ts
@@ -572,6 +572,18 @@ export function promptBridgeLedgerForRun(
}
}
+/**
+ * The run anchor, read from PostgreSQL rather than the runner.
+ *
+ * R2-L4: the ledger queries filter on `inv.created_at >= startedAt`, and
+ * `created_at` is written by the database. Anchoring with the runner's clock
+ * compares two unsynchronised clocks, so a few seconds of skew either drops
+ * the run's own rows or picks up an earlier one. Same clock, both sides.
+ */
+export function profilesNow(): string {
+ return profilesSql('SELECT now()::text').trim()
+}
+
export type PromptBridgeAttemptRow = {
attemptIndex: number
targetRef: string
diff --git a/docs/crds/workflowrecipe.md b/docs/crds/workflowrecipe.md
index 1698a18a8..d5aefdfcf 100644
--- a/docs/crds/workflowrecipe.md
+++ b/docs/crds/workflowrecipe.md
@@ -1374,7 +1374,7 @@ Declaring this block forces an always-on `mcp-host`. Runtime enforcement is addi
| Field | Type | Required | Description |
| -------------------------------------------- | -------- | --------- | --------------------------------------------------------------------------- |
| `promptBridge.allowedModels` | string[] | No | Max 32. |
-| `promptBridge.maxOutputTokens` | integer | No | Min 1. **Deprecated:** accepted but ignored; the Codex ChatGPT wire discards `max_output_tokens`, so nothing capped the response by token count. Removal planned. |
+| `promptBridge.maxOutputTokens` | integer | No | Min 1. Enforced as `max_tokens` on API-key providers (OpenAI, Claude, Z.AI, Bedrock, Google). `codex-subscription` cannot bind it: the ChatGPT wire rejects `max_output_tokens`, so there the ceiling only shapes the authorize request identity and the enforced bound is the contract limit of 16384. |
| `promptBridge.maxRequestsPerRun` | integer | No | Min 1. **Deprecated:** accepted but ignored; platform per-minute rate limits apply. Removal planned. |
| `promptBridge.maxConcurrentInvocations` | integer | No | Min 1. Runtime default 5. |
| `promptBridge.maxInvocationsPerMinute` | integer | No | Min 1. Platform default 120 when unset (ENV `CONTROL_API_PLUGIN_SDK_PROMPTBRIDGE_PER_MIN`, issue #348). |
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 152eba93b..987c638ff 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.315",
+ "version": "0.1.316",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.315",
+ "version": "0.1.316",
"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 f3b8b5f24..cf34181ce 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.315",
+ "version": "0.1.316",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/pluginWorkloadSdk/promptBridge/handler.test.ts b/mcp-host/src/pluginWorkloadSdk/promptBridge/handler.test.ts
index 0c50bc889..227b0e507 100644
--- a/mcp-host/src/pluginWorkloadSdk/promptBridge/handler.test.ts
+++ b/mcp-host/src/pluginWorkloadSdk/promptBridge/handler.test.ts
@@ -45,6 +45,7 @@ function authorization(overrides: Record<string, unknown> = {}) {
attemptGeneration: 1,
policyRevision: 7,
policyHash: 'a'.repeat(64),
+ maxOutputTokens: null,
...overrides,
}
}
@@ -206,18 +207,44 @@ describe('PromptBridgeHandler', () => {
)
})
- it('forwards the workload maxTokens verbatim and applies no grant cap (J8)', async () => {
+ // R4-H2. J8 dropped the clamp on the premise that nothing enforced the
+ // ceiling. That held only for codex-subscription, whose ChatGPT wire rejects
+ // `max_output_tokens`; every API-key provider does send it, so for them the
+ // per-grant cap was a working billing control that the removal silenced.
+ it('clamps the workload maxTokens down to the grant ceiling', async () => {
+ const authorize = vi.fn().mockResolvedValue(authorization({ maxOutputTokens: 4096 }))
+ const { handler, complete } = makeDeps({ authorize })
+ await handler.handle({ ...validBody, maxTokens: 9000 }, 'api')
+ expect(complete).toHaveBeenCalledWith(expect.objectContaining({ maxTokens: 4096 }))
+ })
+
+ it('applies the grant ceiling when the workload names no maxTokens', async () => {
+ const authorize = vi.fn().mockResolvedValue(authorization({ maxOutputTokens: 4096 }))
+ const { handler, complete } = makeDeps({ authorize })
+ await handler.handle(validBody, 'api')
+ expect(complete).toHaveBeenCalledWith(expect.objectContaining({ maxTokens: 4096 }))
+ })
+
+ it('passes the workload maxTokens through when the grant sets no ceiling', async () => {
const { handler, complete } = makeDeps()
await handler.handle({ ...validBody, maxTokens: 9000 }, 'api')
expect(complete).toHaveBeenCalledWith(expect.objectContaining({ maxTokens: 9000 }))
})
- it('sends no maxTokens when the workload asks for none (J8)', async () => {
+ it('sends no maxTokens when neither the workload nor the grant names one', async () => {
const { handler, complete } = makeDeps()
await handler.handle(validBody, 'api')
expect(complete.mock.calls[0]?.[0]).toMatchObject({ maxTokens: undefined })
})
+ it.each([0, -1, 1.5])('rejects a non-positive-integer maxTokens (%s)', async maxTokens => {
+ const { handler, complete } = makeDeps()
+ await expect(handler.handle({ ...validBody, maxTokens }, 'api')).rejects.toMatchObject({
+ code: 'invalid_request',
+ })
+ expect(complete).not.toHaveBeenCalled()
+ })
+
it('preserves metering when the logical terminal acknowledgement is unavailable', async () => {
const report = vi.fn().mockRejectedValue(new Error('control-api unavailable'))
const onUsage = vi.fn()
diff --git a/mcp-host/src/pluginWorkloadSdk/promptBridge/handler.ts b/mcp-host/src/pluginWorkloadSdk/promptBridge/handler.ts
index 7e8108dc6..85913afe8 100644
--- a/mcp-host/src/pluginWorkloadSdk/promptBridge/handler.ts
+++ b/mcp-host/src/pluginWorkloadSdk/promptBridge/handler.ts
@@ -245,8 +245,13 @@ export function validatePromptBridgeRequest(raw: unknown): PromptBridgeRequest {
if (body.modelPolicyRef !== undefined && typeof body.modelPolicyRef !== 'string') {
throw new PluginWorkloadError('invalid_request', 'modelPolicyRef must be a string')
}
- if (body.maxTokens !== undefined && typeof body.maxTokens !== 'number') {
- throw new PluginWorkloadError('invalid_request', 'maxTokens must be a number')
+ if (
+ body.maxTokens !== undefined &&
+ (typeof body.maxTokens !== 'number' || !Number.isInteger(body.maxTokens) || body.maxTokens < 1)
+ ) {
+ // R4-H2: `typeof number` alone let 0, -1 and 1.5 through to the provider
+ // and made the grant clamp's Math.min ill-defined.
+ throw new PluginWorkloadError('invalid_request', 'maxTokens must be a positive integer')
}
if (body.temperature !== undefined && typeof body.temperature !== 'number') {
throw new PluginWorkloadError('invalid_request', 'temperature must be a number')
@@ -429,12 +434,13 @@ export class PromptBridgeHandler {
acknowledgementMode: this.deps.finalizePromptBridge
? 'atomic_terminal_finalization'
: 'per_attempt',
- // J8: the workload's own maxTokens is the only value on this seam. The
- // grant no longer advertises an output cap, because nothing enforced it:
- // Codex ChatGPT `/codex/responses` rejects max_output_tokens and the
- // proxy omits it, so the clamp bounded only the hashed request shape
- // while the real call ran uncapped.
- maxTokens: request.maxTokens,
+ // R4-H2: the per-grant ceiling is enforced here, before the request
+ // reaches any provider. On API-key providers it lands as `max_tokens`
+ // on the wire; on codex-subscription it bounds the hashed request
+ // identity while the proxy omits it from the ChatGPT wire, which also
+ // keeps a capped grant eligible for failover instead of failing the
+ // contract's 16384 range check outright.
+ maxTokens: clampMaxTokens(request.maxTokens, authorized.maxOutputTokens),
temperature: request.temperature ?? authorized.modelPolicy?.temperature,
timeoutMs: this.deps.promptTimeoutMs,
recipeNamespace: this.deps.recipeNamespace,
@@ -654,3 +660,27 @@ function unexpectedAuthorizationResponse(): PluginWorkloadError {
false
)
}
+
+/**
+ * Bound a workload's requested output against the grant's ceiling.
+ *
+ * Scope, stated honestly (R4-H2): on API-key providers this is the real cap —
+ * `max_tokens` reaches the provider. On codex-subscription the ChatGPT wire
+ * rejects `max_output_tokens` and the proxy omits it, so there the clamp bounds
+ * the hashed request identity rather than the response, and the enforced bound
+ * is the contract's structural `LIMITS.maxOutputTokens`. It still matters
+ * there: an unclamped request above that limit fails the contract range check
+ * as a non-retryable error, which is terminal with no failover.
+ *
+ * A grant with no ceiling passes the request through; a workload that names no
+ * maxTokens inherits the ceiling. Both inputs are validated upstream, so the
+ * `Math.min` is over two positive integers.
+ */
+function clampMaxTokens(
+ requested: number | undefined,
+ grantCap: number | null
+): number | undefined {
+ if (grantCap === null) return requested
+ if (requested === undefined) return grantCap
+ return Math.min(requested, grantCap)
+}
diff --git a/workflow-recipes/package-lock.json b/workflow-recipes/package-lock.json
index 5dba5dd9f..73b6c46b0 100644
--- a/workflow-recipes/package-lock.json
+++ b/workflow-recipes/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "workload-recipes-controller",
- "version": "0.1.333",
+ "version": "0.1.334",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "workload-recipes-controller",
- "version": "0.1.333",
+ "version": "0.1.334",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@aws-sdk/client-s3": "^3.1009.0",
diff --git a/workflow-recipes/package.json b/workflow-recipes/package.json
index 2726ba936..19ae9f239 100644
--- a/workflow-recipes/package.json
+++ b/workflow-recipes/package.json
@@ -1,6 +1,6 @@
{
"name": "workload-recipes-controller",
- "version": "0.1.333",
+ "version": "0.1.334",
"description": "Workload Recipes Controller (WRC) - WorkloadRecipe lifecycle management and MCP server interface",
"main": "dist/main.js",
"engines": {
diff --git a/workflow-recipes/src/types.ts b/workflow-recipes/src/types.ts
index 66dd006ce..b03be713b 100644
--- a/workflow-recipes/src/types.ts
+++ b/workflow-recipes/src/types.ts
@@ -507,7 +507,7 @@ export interface OAuthClientDef {
export interface PluginWorkloadSdkSpec {
promptBridge?: {
allowedModels?: string[]
- /** @deprecated Accepted for compatibility; no longer enforced (J8). The Codex ChatGPT wire discards max_output_tokens, so no layer capped the response by token count. */
+ /** Per-grant output ceiling. Enforced as `max_tokens` on API-key providers; codex-subscription cannot bind it on the ChatGPT wire and is bounded there by the contract limit of 16384 instead (R4-H2). */
maxOutputTokens?: number
/** @deprecated Accepted for compatibility; no longer enforced (issue #348). Platform per-minute rate limits apply. */
maxRequestsPerRun?: number
@@ -549,7 +549,7 @@ export interface PluginWorkloadSdkSpec {
export interface PluginWorkloadSdkSnippetConfig {
promptBridge?: {
allowedModels?: string[]
- /** @deprecated Accepted for compatibility; no longer enforced (J8). The Codex ChatGPT wire discards max_output_tokens, so no layer capped the response by token count. */
+ /** Per-grant output ceiling. Enforced as `max_tokens` on API-key providers; codex-subscription cannot bind it on the ChatGPT wire and is bounded there by the contract limit of 16384 instead (R4-H2). */
maxOutputTokens?: number
}
clientNotifications?: {