Skip to content

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

TypeScript

fix(sdk): tie the Codex binding to the catalog and credential revisions

Alfredo Lopez2cc4a16601e2
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index 79765c78a..2bae35174 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.537",
+ "version": "0.1.538",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.537",
+ "version": "0.1.538",
"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 53e51c3af..239e4d542 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.537",
+ "version": "0.1.538",
"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/mcp-host/plugin-workload-sdk.routes.ts b/control-api/src/routes/mcp-host/plugin-workload-sdk.routes.ts
index d2cabdf47..66f5cfca1 100644
--- a/control-api/src/routes/mcp-host/plugin-workload-sdk.routes.ts
+++ b/control-api/src/routes/mcp-host/plugin-workload-sdk.routes.ts
@@ -8,6 +8,7 @@ import { requireMcpHostJwt } from '../../middleware/mcpHostJwtAuth.js'
import { createPluginWorkloadSdkRequestRateLimit } from '../../middleware/pluginWorkloadSdkRateLimits.js'
import { rateLimitMiddleware } from '../../middleware/rateLimitMiddleware.js'
import { pluginWorkloadSdkNotificationAuthDurationSeconds } from '../../observability/metrics.js'
+import { getSafeCodexSubscriptionConnection } from '../../services/codexSubscriptionConnection.js'
import { enqueuePluginWorkloadSdkNotification } from '../../services/notificationEmitter.js'
import {
type PluginWorkloadSdkAuthzError,
@@ -732,6 +733,22 @@ export function createMcpHostPluginWorkloadSdkRoutes(): Router {
// Old mcp-host/WRC require capabilities.contractVersion === 2. Advertise
// 3 only for oauth-broker defaults so those binaries fail at reconcile
// instead of Validated-then-empty-ticket. Authorize/grant wire stays 2.
+ //
+ // #533 acceptance criterion 2 ties the Codex binding to the catalog and
+ // credential revisions, but those live on the connection row and never
+ // reached the host, so `codexBindingReady` could not compare them. They
+ // are advertised additively, gated by `codexBindingRevisions`, because
+ // the two rollout directions need opposite defaults: a host that
+ // predates the fields ignores them, and a host that postdates them must
+ // learn whether THIS API can send them at all — otherwise it would fail
+ // closed against an older control-api on a field that peer cannot emit,
+ // which is the #540 failure shape. Omitting the comparison is a
+ // readiness gap, never an unfenced spend: llmProviderAttemptAuthorizer
+ // and llmProviderAttemptRedemption already reject a stale revision.
+ const codexConnection =
+ reservationOnlyOauthBroker && typeof alignedPrimary?.connectionRef === 'string'
+ ? await getSafeCodexSubscriptionConnection(pool, alignedPrimary.connectionRef)
+ : null
res.status(200).json({
contractVersion: reservationOnlyOauthBroker
? 3
@@ -749,6 +766,13 @@ export function createMcpHostPluginWorkloadSdkRoutes(): Router {
defaultConnectionRef: alignedPrimary?.connectionRef ?? null,
v2Ready,
...(reservationOnlyOauthBroker ? { reservationOnlyOauthBroker: true } : {}),
+ ...(codexConnection
+ ? {
+ codexBindingRevisions: true,
+ defaultCatalogRevision: codexConnection.catalogRevision,
+ defaultCredentialRevision: codexConnection.credentialRevision,
+ }
+ : {}),
clientNotificationsPolicyState: clientNotificationsGrant?.policyState ?? 'missing',
clientNotificationsReady,
})
diff --git a/control-api/test/routes.mcp-host.plugin-workload-sdk.test.ts b/control-api/test/routes.mcp-host.plugin-workload-sdk.test.ts
index 9f376b1b9..737ac09f4 100644
--- a/control-api/test/routes.mcp-host.plugin-workload-sdk.test.ts
+++ b/control-api/test/routes.mcp-host.plugin-workload-sdk.test.ts
@@ -3,6 +3,7 @@ import express from 'express'
import request from 'supertest'
import { pool } from '../src/db.js'
import { createMcpHostPluginWorkloadSdkRoutes } from '../src/routes/mcp-host/plugin-workload-sdk.routes.js'
+import * as codexConnection from '../src/services/codexSubscriptionConnection.js'
import * as notificationEmitter from '../src/services/notificationEmitter.js'
import * as authorizer from '../src/services/pluginWorkloadSdkAuthorizer.js'
import { issuePluginWorkloadSdkCredentialTicket } from '../src/services/pluginWorkloadSdkCredentialTicket.js'
@@ -26,6 +27,13 @@ vi.mock('../src/services/notificationEmitter.js', () => ({
enqueuePluginWorkloadSdkNotification: vi.fn().mockResolvedValue(undefined),
}))
+vi.mock('../src/services/codexSubscriptionConnection.js', async () => {
+ const actual = await vi.importActual<
+ typeof import('../src/services/codexSubscriptionConnection.js')
+ >('../src/services/codexSubscriptionConnection.js')
+ return { ...actual, getSafeCodexSubscriptionConnection: vi.fn() }
+})
+
vi.mock('../src/services/pluginWorkloadSdkDb.js', async () => {
const actual = await vi.importActual<typeof import('../src/services/pluginWorkloadSdkDb.js')>(
'../src/services/pluginWorkloadSdkDb.js'
@@ -126,6 +134,7 @@ beforeEach(() => {
vi.mocked(sdkDb.getPluginWorkloadSdkProviderAttempt).mockReset()
vi.mocked(sdkDb.hasUsableClientNotificationRecipients).mockReset()
vi.mocked(sdkDb.findGrant).mockReset()
+ vi.mocked(codexConnection.getSafeCodexSubscriptionConnection).mockReset().mockResolvedValue(null)
vi.mocked(sdkDb.redeemPluginWorkloadSdkCredentialTicketJti).mockReset()
vi.mocked(sdkDb.markPluginWorkloadSdkProviderAttemptStatus).mockReset()
vi.mocked(notificationEmitter.enqueuePluginWorkloadSdkNotification)
@@ -326,6 +335,94 @@ describe('GET /mcp-host/plugin-workload-sdk/capabilities', () => {
})
})
+ // #533 acceptance criterion 2 — the host cannot tie the binding to the
+ // catalog/credential revisions unless this endpoint publishes them, because
+ // they are authoritative only on the connection row.
+ const codexGrant = () => ({
+ id: 'grant-codex-revisions',
+ recipeNamespace: NS,
+ recipeName: RECIPE,
+ capabilityFamily: 'promptBridge' as const,
+ provider: 'codex-subscription',
+ allowedModels: ['gpt-5.1'],
+ allowedEventTypes: [],
+ allowedTargetRefs: [],
+ allowedUserRefs: [],
+ allowedCallers: ['api'],
+ quotaLimits: {},
+ modelPolicies: {},
+ promptTargets: [
+ {
+ targetRef: 'primary-codex',
+ provider: 'codex-subscription',
+ model: 'gpt-5.1',
+ credentialSlot: '',
+ connectionRef: 'team-plus',
+ },
+ ],
+ defaultTargetRef: 'primary-codex',
+ policyState: 'active' as const,
+ policyRevision: 2,
+ createdAt: '2026-08-03T00:00:00.000Z',
+ updatedAt: '2026-08-03T00:00:00.000Z',
+ })
+
+ it('publishes the authoritative Codex revisions for an oauth-broker default', async () => {
+ vi.mocked(sdkDb.findGrant).mockResolvedValue(codexGrant())
+ vi.mocked(codexConnection.getSafeCodexSubscriptionConnection).mockResolvedValue({
+ id: 'conn-1',
+ connectionKey: 'team-plus',
+ displayName: 'Team Plus',
+ defaultModel: 'gpt-5.1',
+ createdBy: null,
+ status: 'connected',
+ credentialRevision: 3,
+ catalogRevision: 7,
+ accountFingerprint: null,
+ catalogStatus: 'ready',
+ catalogSyncedAt: null,
+ lastRefreshAt: null,
+ lastAuthAt: null,
+ refreshLockHeld: false,
+ revokedAt: null,
+ createdAt: new Date('2026-08-03T00:00:00.000Z'),
+ updatedAt: new Date('2026-08-03T00:00:00.000Z'),
+ })
+
+ const res = await request(buildApp())
+ .get('/mcp-host/plugin-workload-sdk/capabilities')
+ .set('Authorization', `Bearer ${issueSdkToken()}`)
+
+ expect(res.status).toBe(200)
+ expect(res.body).toMatchObject({
+ codexBindingRevisions: true,
+ defaultCatalogRevision: 7,
+ defaultCredentialRevision: 3,
+ })
+ expect(vi.mocked(codexConnection.getSafeCodexSubscriptionConnection)).toHaveBeenCalledWith(
+ expect.anything(),
+ 'team-plus'
+ )
+ })
+
+ it('omits the revision flag entirely when the Codex connection does not resolve', async () => {
+ // The flag is a promise to send both values. A revoked or missing
+ // connection must drop all three together, never advertise the flag over
+ // absent numbers — a host that trusted it would fail closed forever.
+ vi.mocked(sdkDb.findGrant).mockResolvedValue(codexGrant())
+ vi.mocked(codexConnection.getSafeCodexSubscriptionConnection).mockResolvedValue(null)
+
+ const res = await request(buildApp())
+ .get('/mcp-host/plugin-workload-sdk/capabilities')
+ .set('Authorization', `Bearer ${issueSdkToken()}`)
+
+ expect(res.status).toBe(200)
+ expect(res.body.reservationOnlyOauthBroker).toBe(true)
+ expect(res.body.codexBindingRevisions).toBeUndefined()
+ expect(res.body.defaultCatalogRevision).toBeUndefined()
+ expect(res.body.defaultCredentialRevision).toBeUndefined()
+ })
+
it('does not advertise oauth-broker v3 when promptTargets[0] is not the default', async () => {
vi.mocked(sdkDb.findGrant).mockResolvedValue({
id: 'grant-misaligned-capabilities',
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 792528ec0..006bedfb5 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.312",
+ "version": "0.1.313",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.312",
+ "version": "0.1.313",
"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 857b26e11..f174fb25d 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.312",
+ "version": "0.1.313",
"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/controlApiClient.test.ts b/mcp-host/src/pluginWorkloadSdk/promptBridge/controlApiClient.test.ts
index 0ef46fa6f..722b6353a 100644
--- a/mcp-host/src/pluginWorkloadSdk/promptBridge/controlApiClient.test.ts
+++ b/mcp-host/src/pluginWorkloadSdk/promptBridge/controlApiClient.test.ts
@@ -209,6 +209,135 @@ describe('PluginWorkloadSdkControlApiClient', () => {
})
})
+ // #533 acceptance criterion 2 — the binding must also be tied to the catalog
+ // and credential revisions. They are authoritative on control-api, so the
+ // comparison exists only when the peer publishes them; these five cases pin
+ // every combination, including the deliberate mixed-binary compromise.
+ const codexCapabilities = (extra: Record<string, unknown>) => ({
+ contractVersion: 3,
+ supportedContractVersions: [2, 3],
+ reservationOnlyOauthBroker: true,
+ targetAwarePromptBridge: true,
+ attemptLedger: true,
+ credentialTickets: true,
+ policyState: 'active',
+ policyRevision: 2,
+ policyHash: 'a'.repeat(64),
+ defaultTargetRef: 'codex-primary',
+ defaultProvider: 'codex-subscription',
+ defaultModel: 'gpt-5.1',
+ defaultConnectionRef: 'team-plus',
+ v2Ready: true,
+ clientNotificationsPolicyState: 'missing',
+ clientNotificationsReady: false,
+ ...extra,
+ })
+
+ it('marks the Codex binding ready when the published revisions match it', async () => {
+ installCodexBinding()
+ const fetchImpl = vi.fn().mockResolvedValue(
+ jsonResponse(
+ 200,
+ codexCapabilities({
+ codexBindingRevisions: true,
+ defaultCatalogRevision: 4,
+ defaultCredentialRevision: 1,
+ })
+ )
+ )
+ const client = makeClient(fetchImpl as unknown as typeof fetch)
+
+ await expect(
+ client.verifyPromptBridgeBootstrapV2('codex-subscription', 'gpt-5.1')
+ ).resolves.toMatchObject({ policyReady: true, codexBindingReady: true })
+ })
+
+ it('refuses a binding whose catalog revision is behind the published one', async () => {
+ installCodexBinding()
+ const fetchImpl = vi.fn().mockResolvedValue(
+ jsonResponse(
+ 200,
+ codexCapabilities({
+ codexBindingRevisions: true,
+ defaultCatalogRevision: 5,
+ defaultCredentialRevision: 1,
+ })
+ )
+ )
+ const client = makeClient(fetchImpl as unknown as typeof fetch)
+
+ await expect(
+ client.verifyPromptBridgeBootstrapV2('codex-subscription', 'gpt-5.1')
+ ).resolves.toMatchObject({
+ policyReady: false,
+ policyReason: 'codex_execution_binding_missing',
+ codexBindingReady: false,
+ })
+ })
+
+ it('refuses a binding whose credential revision is behind the published one', async () => {
+ installCodexBinding()
+ const fetchImpl = vi.fn().mockResolvedValue(
+ jsonResponse(
+ 200,
+ codexCapabilities({
+ codexBindingRevisions: true,
+ defaultCatalogRevision: 4,
+ defaultCredentialRevision: 2,
+ })
+ )
+ )
+ const client = makeClient(fetchImpl as unknown as typeof fetch)
+
+ await expect(
+ client.verifyPromptBridgeBootstrapV2('codex-subscription', 'gpt-5.1')
+ ).resolves.toMatchObject({
+ policyReady: false,
+ policyReason: 'codex_execution_binding_missing',
+ codexBindingReady: false,
+ })
+ })
+
+ it('refuses the binding when the peer claims revisions but omits one', async () => {
+ // A partial deploy must not read as agreement: the flag is the peer's
+ // promise to send both values, so a missing one is a broken promise.
+ installCodexBinding()
+ const fetchImpl = vi
+ .fn()
+ .mockResolvedValue(
+ jsonResponse(
+ 200,
+ codexCapabilities({ codexBindingRevisions: true, defaultCredentialRevision: 1 })
+ )
+ )
+ const client = makeClient(fetchImpl as unknown as typeof fetch)
+
+ await expect(
+ client.verifyPromptBridgeBootstrapV2('codex-subscription', 'gpt-5.1')
+ ).resolves.toMatchObject({
+ policyReady: false,
+ policyReason: 'codex_execution_binding_missing',
+ codexBindingReady: false,
+ })
+ })
+
+ it('keeps the binding ready against an API that predates the revision fields', async () => {
+ // Deliberate: demanding a field an older control-api cannot emit would
+ // fail closed across a mixed-binary window (the #540 shape). This is not
+ // unfenced — authorize and redeem still reject a stale revision — so the
+ // cost is that a stale binding surfaces at the first prompt instead of at
+ // reconcile. Do not "fix" this into a fail-closed branch.
+ installCodexBinding()
+ const fetchImpl = vi
+ .fn()
+ .mockResolvedValue(jsonResponse(200, codexCapabilities({ defaultCatalogRevision: 999 })))
+ const client = makeClient(fetchImpl as unknown as typeof fetch)
+
+ await expect(
+ client.verifyPromptBridgeBootstrapV2('codex-subscription', 'gpt-5.1')
+ ).resolves.toMatchObject({ policyReady: true, codexBindingReady: true })
+ })
+
it('keeps request-time policy readiness separate from identity bootstrap', async () => {
const fetchImpl = vi.fn().mockResolvedValue(
jsonResponse(200, {
diff --git a/mcp-host/src/pluginWorkloadSdk/promptBridge/controlApiClient.ts b/mcp-host/src/pluginWorkloadSdk/promptBridge/controlApiClient.ts
index 86d3147d3..dac54c986 100644
--- a/mcp-host/src/pluginWorkloadSdk/promptBridge/controlApiClient.ts
+++ b/mcp-host/src/pluginWorkloadSdk/promptBridge/controlApiClient.ts
@@ -69,6 +69,14 @@ export interface PluginWorkloadSdkCapabilities {
v2Ready: boolean
/** Present only when the grant default is oauth-broker (reservation-only Codex). */
reservationOnlyOauthBroker?: true
+ /**
+ * Present only when this control-api can publish the authoritative Codex
+ * catalog/credential revisions. Absent means the peer predates them, not
+ * that the binding is stale — see `codexBindingReady`.
+ */
+ codexBindingRevisions?: true
+ defaultCatalogRevision?: number
+ defaultCredentialRevision?: number
clientNotificationsPolicyState: string
clientNotificationsReady: boolean
}
@@ -211,6 +219,13 @@ function isPluginWorkloadSdkCapabilities(v: unknown): v is PluginWorkloadSdkCapa
typeof value.defaultConnectionRef === 'string') &&
typeof value.v2Ready === 'boolean' &&
(value.reservationOnlyOauthBroker === undefined || value.reservationOnlyOauthBroker === true) &&
+ (value.codexBindingRevisions === undefined || value.codexBindingRevisions === true) &&
+ (value.defaultCatalogRevision === undefined ||
+ (Number.isInteger(value.defaultCatalogRevision) &&
+ Number(value.defaultCatalogRevision) >= 1)) &&
+ (value.defaultCredentialRevision === undefined ||
+ (Number.isInteger(value.defaultCredentialRevision) &&
+ Number(value.defaultCredentialRevision) >= 0)) &&
typeof value.clientNotificationsPolicyState === 'string' &&
typeof value.clientNotificationsReady === 'boolean'
)
@@ -603,6 +618,23 @@ export class PluginWorkloadSdkControlApiClient {
const reservationOnlyReady = capabilities.reservationOnlyOauthBroker === true
const contractReady =
capabilities.contractVersion === 3 && capabilities.supportedContractVersions.includes(3)
+ // #533 acceptance criterion 2: the binding must be tied to the catalog and
+ // credential revisions too, not only to the connection and model. Those
+ // revisions are authoritative on control-api's connection row, so this can
+ // only be compared when the peer publishes them. `codexBindingRevisions`
+ // is that discriminator, and it must be read as "can this API send them",
+ // never as "is this binding fresh": an older control-api omits the flag,
+ // and demanding a field it cannot emit would fail closed across a
+ // mixed-binary window (the #540 shape). When the flag IS present, both
+ // values are required and must match — a missing or divergent revision is
+ // a stale binding, and it fails closed here at reconcile rather than at
+ // the first prompt.
+ const revisionsPublished = capabilities.codexBindingRevisions === true
+ const codexRevisionsReady =
+ !revisionsPublished ||
+ (binding !== null &&
+ capabilities.defaultCatalogRevision === binding.catalogRevision &&
+ capabilities.defaultCredentialRevision === binding.credentialRevision)
const codexBindingReady =
expectedProvider !== 'codex-subscription' ||
(reservationOnlyReady &&
@@ -612,7 +644,8 @@ export class PluginWorkloadSdkControlApiClient {
capabilities.defaultModel === expectedModel &&
binding.model === expectedModel &&
typeof capabilities.defaultConnectionRef === 'string' &&
- capabilities.defaultConnectionRef === binding.connectionKey)
+ capabilities.defaultConnectionRef === binding.connectionKey &&
+ codexRevisionsReady)
const policyReady =
capabilities.v2Ready &&
capabilities.policyRevision >= 1 &&