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.jsonindex 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.jsonindex 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.tsindex 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)+ : nullres.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.tsindex 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.jsonindex 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.jsonindex 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.tsindex 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.tsindex 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?: numberclientNotificationsPolicyState: stringclientNotificationsReady: boolean}@@ -211,6 +219,13 @@ function isPluginWorkloadSdkCapabilities(v: unknown): v is PluginWorkloadSdkCapatypeof 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 === trueconst 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 &&