Skip to content

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

TypeScript

feat(sdk): mint Grok subscriptionBinding independently of Codex

Jose Gabriel Ramirez Encinasd4d8fd6a84bc
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index 358a89549..ea680ad61 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.559",
+ "version": "0.1.560",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.559",
+ "version": "0.1.560",
"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 b89bc1bbf..58f7c58a3 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.559",
+ "version": "0.1.560",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/services/grokSubscriptionOAuth.ts b/control-api/src/services/grokSubscriptionOAuth.ts
index 606a0ca97..938d0df87 100644
--- a/control-api/src/services/grokSubscriptionOAuth.ts
+++ b/control-api/src/services/grokSubscriptionOAuth.ts
@@ -581,7 +581,7 @@ async function exchangeRefreshToken(
refresh_token: refreshToken,
client_id: deps.clientId,
})
- if (result.status === 403) {
+ if (result.status === 402 || result.status === 403) {
throw new GrokSubscriptionOAuthError('provider_unavailable', 'refresh was entitlement-denied')
}
if (!result.ok) {
diff --git a/control-api/src/services/llmProviderAttemptAuthorizer.ts b/control-api/src/services/llmProviderAttemptAuthorizer.ts
index 58c7c058f..873eeaa4b 100644
--- a/control-api/src/services/llmProviderAttemptAuthorizer.ts
+++ b/control-api/src/services/llmProviderAttemptAuthorizer.ts
@@ -26,6 +26,7 @@ import {
import { issueRegisteredGrokExecutionTicket } from './grokProviderAttemptTicket.js'
import { getGrokCatalogModelState } from './grokSubscriptionCatalog.js'
import {
+ GROK_RESERVED_DEPLOYMENT_DEFAULT_KEY,
GROK_UNASSIGNED_CONNECTION_KEY,
getSafeGrokSubscriptionConnection,
isGrokUnassignedConnectionKey,
@@ -306,7 +307,8 @@ async function authorizeGrokProviderAttempt(
const connectionKey = attested.connectionKey
if (
isGrokUnassignedConnectionKey(connectionKey) ||
- connectionKey === GROK_UNASSIGNED_CONNECTION_KEY
+ connectionKey === GROK_UNASSIGNED_CONNECTION_KEY ||
+ connectionKey === GROK_RESERVED_DEPLOYMENT_DEFAULT_KEY
) {
throw new LlmProviderAttemptAuthorizeError(
'unassigned_connection',
diff --git a/control-api/src/services/subscriptionGrantIdentity.ts b/control-api/src/services/subscriptionGrantIdentity.ts
index 7caac20c9..ebf269286 100644
--- a/control-api/src/services/subscriptionGrantIdentity.ts
+++ b/control-api/src/services/subscriptionGrantIdentity.ts
@@ -135,7 +135,8 @@ export function attestRequestedBrokerProvider(input: {
const connectionKey = readHostCodexConnectionRef(input.liveConnectionRef)
if (
isCodexUnassignedConnectionKey(connectionKey) ||
- connectionKey === CODEX_UNASSIGNED_CONNECTION_KEY
+ connectionKey === CODEX_UNASSIGNED_CONNECTION_KEY ||
+ (input.requestedProvider === 'grok-subscription' && connectionKey === 'deployment-default')
) {
return {
ok: false,
diff --git a/control-api/test/services.grokSubscriptionOAuth.test.ts b/control-api/test/services.grokSubscriptionOAuth.test.ts
index cfbfeb9b0..828c4cfac 100644
--- a/control-api/test/services.grokSubscriptionOAuth.test.ts
+++ b/control-api/test/services.grokSubscriptionOAuth.test.ts
@@ -301,6 +301,31 @@ describe('grok subscription OAuth device broker', () => {
expect(repos.persistRefresh).not.toHaveBeenCalled()
})
+ it('maps refresh 402 to provider_unavailable', async () => {
+ repos.getSafe.mockResolvedValue({
+ connectionKey: CONNECTION_KEY,
+ status: 'connected',
+ credentialRevision: 3,
+ refreshLockHeld: true,
+ })
+ repos.acquireLock.mockResolvedValue(true)
+ repos.loadSecrets.mockResolvedValue({
+ refreshToken: 'old-refresh',
+ accessToken: null,
+ accessTokenExpiresAt: null,
+ credentialRevision: 3,
+ })
+ const fetchFn = vi.fn().mockResolvedValue({
+ ok: false,
+ status: 402,
+ json: async () => ({ error: 'payment_required' }),
+ })
+ await expect(refreshGrokSubscriptionConnection(deps(fetchFn))).rejects.toMatchObject({
+ code: 'provider_unavailable',
+ })
+ expect(repos.persistRefresh).not.toHaveBeenCalled()
+ })
+
it('maps invalid_grant with unchanged lock and revision to reauth_required', async () => {
repos.getSafe.mockResolvedValue({
connectionKey: CONNECTION_KEY,
diff --git a/control-api/test/services.llmProviderAttemptAuthorizer.grok.test.ts b/control-api/test/services.llmProviderAttemptAuthorizer.grok.test.ts
new file mode 100644
index 000000000..069f6d8e7
--- /dev/null
+++ b/control-api/test/services.llmProviderAttemptAuthorizer.grok.test.ts
@@ -0,0 +1,224 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+ computeGrokPolicyHash,
+ hashGrokCompletionRequestV1,
+} from '@clerum/grok-provider-attempt-contract'
+import { config } from '../src/config.js'
+import {
+ LlmProviderAttemptAuthorizeError,
+ type LlmProviderAttemptAuthorizerDeps,
+ authorizeLlmProviderAttempt,
+} from '../src/services/llmProviderAttemptAuthorizer.js'
+import type { McpHostAccessClaims } from '../src/utils/auth/mcpHostJwtToken.js'
+
+const grokRepos = vi.hoisted(() => ({
+ getConnection: vi.fn(),
+ getModelState: vi.fn(),
+ issueTicket: vi.fn(),
+}))
+
+vi.mock('../src/services/grokSubscriptionConnection.js', async () => {
+ const actual = await vi.importActual<
+ typeof import('../src/services/grokSubscriptionConnection.js')
+ >('../src/services/grokSubscriptionConnection.js')
+ return {
+ ...actual,
+ getSafeGrokSubscriptionConnection: grokRepos.getConnection,
+ }
+})
+
+vi.mock('../src/services/grokSubscriptionCatalog.js', async () => {
+ const actual = await vi.importActual<typeof import('../src/services/grokSubscriptionCatalog.js')>(
+ '../src/services/grokSubscriptionCatalog.js'
+ )
+ return {
+ ...actual,
+ getGrokCatalogModelState: grokRepos.getModelState,
+ }
+})
+
+vi.mock('../src/services/grokProviderAttemptTicket.js', async () => {
+ const actual = await vi.importActual<
+ typeof import('../src/services/grokProviderAttemptTicket.js')
+ >('../src/services/grokProviderAttemptTicket.js')
+ return {
+ ...actual,
+ issueRegisteredGrokExecutionTicket: grokRepos.issueTicket,
+ }
+})
+
+const REQUEST = {
+ schemaVersion: 'grok-completion-request.v1' as const,
+ requestId: 'req-001',
+ idempotencyKey: 'idem-001',
+ provider: 'grok-subscription' as const,
+ model: 'grok-4.6',
+ messages: [{ role: 'user' as const, content: 'hello' }],
+}
+
+function claims(overrides: Partial<McpHostAccessClaims> = {}): McpHostAccessClaims {
+ return {
+ sub: 'default/research-host',
+ recipeNamespace: 'default',
+ recipeName: 'research-host',
+ hostRefs: ['research-host'],
+ scope: 'workflow:approval:request',
+ workflowControlScopes: ['llm:grok:execute'],
+ iss: 'control-api',
+ aud: 'workflow-approvals',
+ jti: 'jti-1',
+ exp: Math.floor(Date.now() / 1000) + 60,
+ ...overrides,
+ }
+}
+
+function grokConnection(overrides: Record<string, unknown> = {}) {
+ return {
+ id: '11111111-1111-4111-8111-111111111111',
+ connectionKey: 'team-grok',
+ displayName: 'Team Grok',
+ createdBy: null,
+ status: 'connected',
+ credentialRevision: 3,
+ catalogRevision: 4,
+ accountFingerprint: 'fp',
+ catalogStatus: 'ready',
+ catalogSyncedAt: new Date(),
+ lastRefreshAt: null,
+ lastAuthAt: new Date(),
+ refreshLockHeld: false,
+ revokedAt: null,
+ createdAt: new Date(),
+ updatedAt: new Date(),
+ ...overrides,
+ }
+}
+
+function body(overrides: Record<string, unknown> = {}) {
+ const policyHash = computeGrokPolicyHash({
+ model: REQUEST.model,
+ catalogRevision: 4,
+ credentialRevision: 3,
+ connectionKey: 'team-grok',
+ })
+ return {
+ request: REQUEST,
+ invocationId: 'invocation-1',
+ attemptGeneration: 1,
+ providerAttemptIndex: 1,
+ policyRevision: 4,
+ policyHash,
+ ...overrides,
+ }
+}
+
+function deps(
+ overrides: Partial<LlmProviderAttemptAuthorizerDeps> = {}
+): LlmProviderAttemptAuthorizerDeps {
+ const db = { query: vi.fn() }
+ const resolveConnectionKey =
+ overrides.resolveConnectionKey ?? vi.fn().mockResolvedValue('team-grok')
+ const resolveAssignment =
+ overrides.resolveAssignment ??
+ (async (hostRef: string) => ({
+ liveBrokerProviders: ['grok-subscription'],
+ liveConnectionRef: await resolveConnectionKey(hostRef),
+ }))
+ return {
+ enabled: true,
+ db,
+ withTransaction: async work => work(db as never),
+ getConnection: vi.fn(),
+ getModelState: vi.fn(),
+ evaluateBudget: vi.fn().mockResolvedValue({ allowed: true, reservationIds: ['res-1'] }),
+ getActiveReservation: vi.fn().mockResolvedValue({ id: 'res-1' }),
+ getMaxGeneration: vi.fn().mockResolvedValue(0),
+ insertAttempt: vi.fn().mockResolvedValue({
+ id: '33333333-3333-4333-8333-333333333333',
+ hostRef: 'research-host',
+ }),
+ issueTicket: vi.fn(),
+ ...overrides,
+ resolveConnectionKey,
+ resolveAssignment,
+ }
+}
+
+describe('authorizeLlmProviderAttempt grok-subscription', () => {
+ const previousFlag = config.grokSubscriptionEnabled
+
+ beforeEach(() => {
+ config.grokSubscriptionEnabled = true
+ grokRepos.getConnection.mockReset().mockResolvedValue(grokConnection())
+ grokRepos.getModelState.mockReset().mockResolvedValue({ enabled: true, stale: false })
+ grokRepos.issueTicket.mockReset().mockResolvedValue({
+ executionTicket: 'grok-ticket.jwt',
+ expiresAt: new Date('2026-08-20T12:00:00.000Z'),
+ claims: { jti: 'jti-ticket' },
+ })
+ })
+
+ afterEach(() => {
+ config.grokSubscriptionEnabled = previousFlag
+ })
+
+ it('returns disabled when the Grok flag is off and never looks up a grant', async () => {
+ config.grokSubscriptionEnabled = false
+ const current = deps()
+ await expect(authorizeLlmProviderAttempt(claims(), body(), current)).rejects.toMatchObject({
+ code: 'disabled',
+ } satisfies Partial<LlmProviderAttemptAuthorizeError>)
+ expect(grokRepos.getConnection).not.toHaveBeenCalled()
+ expect(current.insertAttempt).not.toHaveBeenCalled()
+ })
+
+ it('rejects an unassigned Grok Host as unassigned_connection', async () => {
+ const current = deps({
+ resolveConnectionKey: async () => 'unassigned',
+ })
+ await expect(authorizeLlmProviderAttempt(claims(), body(), current)).rejects.toMatchObject({
+ code: 'unassigned_connection',
+ })
+ expect(grokRepos.getConnection).not.toHaveBeenCalled()
+ expect(current.insertAttempt).not.toHaveBeenCalled()
+ })
+
+ it('rejects an empty Grok connectionRef as unassigned, never deployment-default', async () => {
+ const current = deps({
+ resolveConnectionKey: async () => '',
+ })
+ await expect(authorizeLlmProviderAttempt(claims(), body(), current)).rejects.toMatchObject({
+ code: 'unassigned_connection',
+ })
+ expect(grokRepos.getConnection).not.toHaveBeenCalled()
+ })
+
+ it('rejects the reserved deployment-default key on a Grok Host', async () => {
+ const current = deps({
+ resolveConnectionKey: async () => 'deployment-default',
+ })
+ await expect(authorizeLlmProviderAttempt(claims(), body(), current)).rejects.toMatchObject({
+ code: 'unassigned_connection',
+ })
+ expect(grokRepos.getConnection).not.toHaveBeenCalled()
+ expect(current.insertAttempt).not.toHaveBeenCalled()
+ })
+
+ it('authorizes a named Grok grant without treating Codex deployment-default as a fallback', async () => {
+ const current = deps()
+ const result = await authorizeLlmProviderAttempt(claims(), body(), current)
+ expect(result).toMatchObject({
+ providerAttemptId: '33333333-3333-4333-8333-333333333333',
+ executionTicket: 'grok-ticket.jwt',
+ requestHash: hashGrokCompletionRequestV1(REQUEST),
+ })
+ expect(grokRepos.getConnection).toHaveBeenCalledWith(expect.anything(), 'team-grok')
+ expect(current.insertAttempt).toHaveBeenCalledWith(
+ expect.anything(),
+ expect.objectContaining({
+ provider: 'grok-subscription',
+ model: 'grok-4.6',
+ })
+ )
+ })
+})
diff --git a/control-api/test/subscriptionGrantIdentity.test.ts b/control-api/test/subscriptionGrantIdentity.test.ts
index 644eff149..a71ce5af5 100644
--- a/control-api/test/subscriptionGrantIdentity.test.ts
+++ b/control-api/test/subscriptionGrantIdentity.test.ts
@@ -67,6 +67,23 @@ describe('attestRequestedBrokerProvider', () => {
expect(result.ok).toBe(false)
if (!result.ok) expect(result.code).toBe('unassigned_connection')
})
+
+ it('keeps empty Grok connectionRef unassigned and never aliases deployment-default', () => {
+ const empty = attestRequestedBrokerProvider({
+ requestedProvider: 'grok-subscription',
+ liveBrokerProviders: ['grok-subscription'],
+ liveConnectionRef: '',
+ })
+ expect(empty.ok).toBe(false)
+ if (!empty.ok) expect(empty.code).toBe('unassigned_connection')
+ const reserved = attestRequestedBrokerProvider({
+ requestedProvider: 'grok-subscription',
+ liveBrokerProviders: ['grok-subscription'],
+ liveConnectionRef: 'deployment-default',
+ })
+ expect(reserved.ok).toBe(false)
+ if (!reserved.ok) expect(reserved.code).toBe('unassigned_connection')
+ })
})
describe('readSubscriptionConnectionRef', () => {
@@ -96,6 +113,22 @@ describe('readSubscriptionConnectionRef', () => {
})
expect(result.ok).toBe(false)
})
+
+ it('fails closed when a Grok recipe still has the Codex alias leftover', () => {
+ const result = readSubscriptionConnectionRef({
+ provider: 'grok-subscription',
+ annotations: { [CODEX_CONNECTION_REF_ANNOTATION]: 'team-plus' },
+ })
+ expect(result.ok).toBe(false)
+ })
+
+ it('reads only the canonical annotation for Grok', () => {
+ const result = readSubscriptionConnectionRef({
+ provider: 'grok-subscription',
+ annotations: { [SUBSCRIPTION_CONNECTION_REF_ANNOTATION]: 'team-grok' },
+ })
+ expect(result).toEqual({ ok: true, connectionKey: 'team-grok' })
+ })
})
describe('collectRecipeOauthBrokerProviders', () => {
diff --git a/control-ui/app/plugin-workload-sdk/page.tsx b/control-ui/app/plugin-workload-sdk/page.tsx
index da4f3ebd1..def21b349 100644
--- a/control-ui/app/plugin-workload-sdk/page.tsx
+++ b/control-ui/app/plugin-workload-sdk/page.tsx
@@ -36,8 +36,16 @@ import {
listCodexSubscriptionConnections,
} from '@lib/codexSubscription'
import { isDisabledCapabilityError } from '@lib/codexSubscriptionFeature'
+import {
+ type GrokSubscriptionConnectionView,
+ isAssignableGrokGrant,
+ listGrokConnectionModels,
+ listGrokSubscriptionConnections,
+} from '@lib/grokSubscription'
+import { loadGrokSubscriptionCapability } from '@lib/grokSubscriptionFeature'
import { useLlmAllowedModels } from '@lib/hooks/useLlmAllowedModels'
import {
+ GROK_SUBSCRIPTION_PROVIDER,
LLM_PROVIDER_OPTIONS,
type LlmProvider,
OPENAI_SUBSCRIPTION_PROVIDER,
@@ -473,8 +481,12 @@ function GrantFormModal({
// catalog are listed, and the model picker narrows to that grant's enabled
// non-stale models — the same "choose, don't create" lock Hosts follow.
const isCodexProvider = modelProvider === OPENAI_SUBSCRIPTION_PROVIDER
+ const isGrokProvider = modelProvider === GROK_SUBSCRIPTION_PROVIDER
+ const isBrokerProvider = isCodexProvider || isGrokProvider
+ const [grokEnabled, setGrokEnabled] = useState(false)
const [codexConnectionRef, setCodexConnectionRef] = useState('')
const [codexConnections, setCodexConnections] = useState<CodexSubscriptionConnectionView[]>([])
+ const [grokConnections, setGrokConnections] = useState<GrokSubscriptionConnectionView[]>([])
const [codexModels, setCodexModels] = useState<string[]>([])
const [allowedEventTypes, setAllowedEventTypes] = useState(
(grant?.allowedEventTypes ?? []).join(', ')
@@ -558,12 +570,45 @@ function GrantFormModal({
}
}, [isCodexProvider])
useEffect(() => {
- if (!isCodexProvider || !codexConnectionRef) {
+ let cancelled = false
+ loadGrokSubscriptionCapability()
+ .then(capability => {
+ if (!cancelled) setGrokEnabled(capability.enabled)
+ })
+ .catch(() => {
+ if (!cancelled) setGrokEnabled(false)
+ })
+ return () => {
+ cancelled = true
+ }
+ }, [])
+ useEffect(() => {
+ if (!isGrokProvider) return
+ let cancelled = false
+ listGrokSubscriptionConnections()
+ .then(connections => {
+ if (cancelled) return
+ setGrokConnections(connections.filter(isAssignableGrokGrant))
+ })
+ .catch(err => {
+ if (cancelled) return
+ setGrokConnections([])
+ if (!isDisabledCapabilityError(err)) {
+ setError(err instanceof Error ? err.message : 'Could not load Grok subscriptions')
+ }
+ })
+ return () => {
+ cancelled = true
+ }
+ }, [isGrokProvider])
+ useEffect(() => {
+ if (!isBrokerProvider || !codexConnectionRef) {
setCodexModels([])
return
}
let cancelled = false
- listCodexConnectionModels(codexConnectionRef)
+ const loader = isGrokProvider ? listGrokConnectionModels : listCodexConnectionModels
+ loader(codexConnectionRef)
.then(models => {
if (cancelled) return
setCodexModels(models.filter(row => row.enabled && !row.stale).map(row => row.model))
@@ -574,7 +619,7 @@ function GrantFormModal({
return () => {
cancelled = true
}
- }, [isCodexProvider, codexConnectionRef])
+ }, [isBrokerProvider, isGrokProvider, codexConnectionRef])
const [submitting, setSubmitting] = useState(false)
const [error, setError] = useState('')
@@ -652,8 +697,8 @@ function GrantFormModal({
hasWildcard(callersList)
const providerModelOptions = useMemo(
- () => (isCodexProvider ? codexModels : getModelOptions(allowedCatalog, modelProvider)),
- [allowedCatalog, codexModels, isCodexProvider, modelProvider]
+ () => (isBrokerProvider ? codexModels : getModelOptions(allowedCatalog, modelProvider)),
+ [allowedCatalog, codexModels, isBrokerProvider, modelProvider]
)
const credentialSlotOptions = useMemo(
() => getPromptBridgeCredentialSlotOptions(modelProvider, availableCredentialKeys),
@@ -742,7 +787,7 @@ function GrantFormModal({
const ref = targetRef.trim() || `${modelProvider}-${model}-${promptTargets.length + 1}`
// Codex targets bind a permitted subscription grant and carry no static
// Secret slot; API-key targets keep requiring a provider-owned slot.
- if (!model || !ref || (isCodexProvider ? !connectionRef : !slot)) return
+ if (!model || !ref || (isBrokerProvider ? !connectionRef : !slot)) return
if (
promptTargets.some(
target =>
@@ -754,7 +799,7 @@ function GrantFormModal({
}
setPromptTargets(current => [
...current,
- isCodexProvider
+ isBrokerProvider
? { targetRef: ref, provider: modelProvider, model, credentialSlot: '', connectionRef }
: { targetRef: ref, provider: modelProvider, model, credentialSlot: slot },
])
@@ -879,7 +924,9 @@ function GrantFormModal({
setCodexConnectionRef('')
}}
>
- {LLM_PROVIDER_OPTIONS.map(option => (
+ {LLM_PROVIDER_OPTIONS.filter(
+ option => option.value !== GROK_SUBSCRIPTION_PROVIDER || grokEnabled
+ ).map(option => (
<option key={option.value} value={option.value}>
{option.label}
</option>
@@ -911,12 +958,16 @@ function GrantFormModal({
))}
</SelectInput>
</Field>
- {isCodexProvider ? (
+ {isBrokerProvider ? (
<Field
- label="Codex subscription"
+ label={isGrokProvider ? 'Grok subscription' : 'Codex subscription'}
htmlFor="sdk-codex-connection"
required
- description="Choose an existing connected ChatGPT subscription grant. Grants are created in Secrets & Connections; this policy only selects one, and only its enabled models can be added."
+ description={
+ isGrokProvider
+ ? 'Choose an existing connected Grok subscription grant. Grants are created in Secrets & Connections; this policy only selects one.'
+ : 'Choose an existing connected ChatGPT subscription grant. Grants are created in Secrets & Connections; this policy only selects one, and only its enabled models can be added.'
+ }
>
<SelectInput
id="sdk-codex-connection"
@@ -928,7 +979,7 @@ function GrantFormModal({
}}
>
<option value="">Select connected subscription…</option>
- {codexConnections.map(connection => (
+ {(isGrokProvider ? grokConnections : codexConnections).map(connection => (
<option key={connection.connectionKey} value={connection.connectionKey}>
{connection.displayName
? `${connection.displayName} (${connection.connectionKey})`
@@ -980,7 +1031,7 @@ function GrantFormModal({
onClick={addPromptTarget}
disabled={
!targetModel.trim() ||
- (isCodexProvider ? !codexConnectionRef.trim() : !credentialSlot.trim())
+ (isBrokerProvider ? !codexConnectionRef.trim() : !credentialSlot.trim())
}
>
Add target
@@ -996,7 +1047,7 @@ function GrantFormModal({
{target.targetRef}: {getProviderLabel(target.provider as LlmProvider)} /{' '}
{target.model} /{' '}
{target.connectionRef
- ? `sub:${target.connectionRef}`
+ ? `sub:${target.provider}:${target.connectionRef}`
: target.credentialSlot}
</code>
<Button
diff --git a/control-ui/components/__tests__/PluginWorkloadSdkPage.test.tsx b/control-ui/components/__tests__/PluginWorkloadSdkPage.test.tsx
index 926ced242..a65278749 100644
--- a/control-ui/components/__tests__/PluginWorkloadSdkPage.test.tsx
+++ b/control-ui/components/__tests__/PluginWorkloadSdkPage.test.tsx
@@ -40,6 +40,32 @@ vi.mock('@lib/hooks/useLlmAllowedModels', () => ({
useLlmAllowedModels: () => ({ models: [], loading: false, error: '', reload: vi.fn() }),
}))
+const grokCapability = vi.hoisted(() => ({
+ load: vi.fn().mockResolvedValue({ enabled: false }),
+}))
+
+vi.mock('@lib/grokSubscriptionFeature', () => ({
+ loadGrokSubscriptionCapability: (...args: unknown[]) => grokCapability.load(...args),
+}))
+
+vi.mock('@lib/grokSubscription', async importOriginal => {
+ const actual = await importOriginal<typeof import('@lib/grokSubscription')>()
+ return {
+ ...actual,
+ listGrokSubscriptionConnections: vi.fn().mockResolvedValue([
+ {
+ connectionKey: 'team-grok',
+ displayName: 'Team Grok',
+ status: 'connected',
+ catalogStatus: 'ready',
+ },
+ ]),
+ listGrokConnectionModels: vi
+ .fn()
+ .mockResolvedValue([{ model: 'grok-4.6', enabled: true, stale: false }]),
+ }
+})
+
vi.mock('@lib/api', async importOriginal => {
const actual = await importOriginal<typeof import('@lib/api')>()
return {
@@ -104,6 +130,7 @@ function makeGrant(overrides: Partial<PluginWorkloadSdkGrant>): PluginWorkloadSd
}
beforeEach(() => {
+ grokCapability.load.mockResolvedValue({ enabled: false })
vi.mocked(getAdminUsers).mockResolvedValue({ items: [manualUser] })
vi.mocked(getPluginWorkloadSdkLegacyInventory).mockResolvedValue({
totalPromptBridgeGrants: 0,
@@ -184,4 +211,35 @@ describe('Plugin Workload SDK operator page', () => {
expect(await screen.findByText('4/min')).toBeInTheDocument()
expect(screen.getByText('platform defaults')).toBeInTheDocument()
})
+
+ it('hides grok-subscription until the Grok capability probe succeeds', async () => {
+ render(<PluginWorkloadSdkPage />)
+ const newGrant = await screen.findByRole('button', { name: 'New grant' })
+ await waitFor(() => expect(newGrant).toBeEnabled())
+ fireEvent.click(newGrant)
+ const dialog = await screen.findByRole('dialog', { name: 'New SDK grant' })
+ expect(within(dialog).queryByRole('option', { name: /xAI Grok Subscription/i })).toBeNull()
+ })
+
+ it('offers Grok grants in the SDK picker when the Grok flag is on', async () => {
+ grokCapability.load.mockResolvedValue({ enabled: true })
+ render(<PluginWorkloadSdkPage />)
+ const newGrant = await screen.findByRole('button', { name: 'New grant' })
+ await waitFor(() => expect(newGrant).toBeEnabled())
+ fireEvent.click(newGrant)
+ const dialog = await screen.findByRole('dialog', { name: 'New SDK grant' })
+ const provider = await waitFor(() =>
+ within(dialog).getByRole('combobox', { name: /target provider/i })
+ )
+ await waitFor(() => {
+ expect(
+ within(provider).getByRole('option', { name: /xAI Grok Subscription/i })
+ ).toBeInTheDocument()
+ })
+ fireEvent.change(provider, { target: { value: 'grok-subscription' } })
+ expect(
+ await within(dialog).findByRole('combobox', { name: /grok subscription/i })
+ ).toBeInTheDocument()
+ expect(await within(dialog).findByRole('option', { name: /Team Grok/ })).toBeInTheDocument()
+ })
})
diff --git a/control-ui/package-lock.json b/control-ui/package-lock.json
index 03eccd756..74da16267 100644
--- a/control-ui/package-lock.json
+++ b/control-ui/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-ui",
- "version": "0.1.577",
+ "version": "0.1.578",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-ui",
- "version": "0.1.577",
+ "version": "0.1.578",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/frontend-components": "file:../packages/frontend-components",
diff --git a/control-ui/package.json b/control-ui/package.json
index 3028160ce..1b1fd6549 100644
--- a/control-ui/package.json
+++ b/control-ui/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-ui",
- "version": "0.1.577",
+ "version": "0.1.578",
"private": true,
"scripts": {
"dev": "NEXT_IGNORE_INCORRECT_LOCKFILE=1 next dev",
diff --git a/docs/architecture/grok-subscription-transport-contract.md b/docs/architecture/grok-subscription-transport-contract.md
index 5f1c741e7..827ed0a62 100644
--- a/docs/architecture/grok-subscription-transport-contract.md
+++ b/docs/architecture/grok-subscription-transport-contract.md
@@ -51,3 +51,18 @@ Stamped in `grok-llm-proxy`, never taken from mcp-host or the hashed request:
CLI impersonation headers (`x-xai-token-auth`, `x-grok-client-identifier`) stay
off until a recorded SuperGrok probe requires them. Do not send `OpenAI-Beta`
or `service_tier`. `max_output_tokens` is bindable on this wire.
+
+## Allowlist ConfigMap republish
+
+control-api is `replicas: 1`. After rolling a new control-api that writes
+`clerum.io/grok-*` annotations, republish `clerum-llm-allowed-models` once the
+new pod is Ready so a mutation on the old pod cannot strip Grok annotations.
+
+Rollback: drop `llm:grok:execute` and Grok proxy NetworkPolicies in HCC/WRC
+before rolling control-api back. A new control-api republishes on boot.
+
+## SDK bootstrap
+
+Grok writers emit `subscriptionBinding` only. Readers accept `subscriptionBinding`
+or `codexBinding`. Grok missing-binding reason is `execution_binding_missing`.
+Codex keeps `codexBinding` and `codex_execution_binding_missing`.
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index d42966141..6acdbfffa 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.333",
+ "version": "0.1.334",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.333",
+ "version": "0.1.334",
"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 3ee5ab1aa..6df7baaa2 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.333",
+ "version": "0.1.334",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/main.ts b/mcp-host/src/main.ts
index fd07db920..d7f393d34 100644
--- a/mcp-host/src/main.ts
+++ b/mcp-host/src/main.ts
@@ -110,6 +110,7 @@ import {
} from './pluginWorkloadSdk/bootstrapIdentity'
import { PluginWorkloadSdkBootstrapServer } from './pluginWorkloadSdk/bootstrapServer'
import { sdkOnlyBindingAsPolicy } from './pluginWorkloadSdk/sdkOnlyCodexBinding'
+import { sdkOnlyGrokBindingAsPolicy } from './pluginWorkloadSdk/sdkOnlyGrokBinding'
import { maybeCreatePluginWorkloadSdkServer } from './pluginWorkloadSdk/server'
import type { PluginWorkloadSdkServer } from './pluginWorkloadSdk/server/sdkServer'
import { sanitizeError } from './progress/intentExtraction'
@@ -3222,6 +3223,7 @@ async function startPluginWorkloadSdkOnlyMode(): Promise<void> {
console.log(`[Main] Starting in SDK-ONLY MODE (recipe: ${config.workflowRecipeName})`)
setCodexPolicyBindingReader(() => sdkOnlyBindingAsPolicy())
+ setGrokPolicyBindingReader(() => sdkOnlyGrokBindingAsPolicy())
if (!runtimeAuth) runtimeAuth = createMcpHostRuntimeAuth()
if (!runtimeAuth) {
diff --git a/mcp-host/src/pluginWorkloadSdk/bootstrapIdentity.test.ts b/mcp-host/src/pluginWorkloadSdk/bootstrapIdentity.test.ts
index a8622b9df..031a26508 100644
--- a/mcp-host/src/pluginWorkloadSdk/bootstrapIdentity.test.ts
+++ b/mcp-host/src/pluginWorkloadSdk/bootstrapIdentity.test.ts
@@ -1,5 +1,6 @@
import { describe, expect, it, vi } from 'vitest'
import { CODEX_UNASSIGNED_CONNECTION_KEY } from '@clerum/codex-catalog-projection'
+import { computeGrokPolicyHash } from '@clerum/grok-provider-attempt-contract'
import { computeCodexPolicyHash } from '@clerum/llm-provider-attempt-contract'
import {
configurePluginWorkloadSdkBootstrapIdentity,
@@ -11,6 +12,7 @@ import {
readVerifiedSdkOnlyCodexBinding,
replaceSdkOnlyCodexBinding,
} from './sdkOnlyCodexBinding'
+import { readSdkOnlyGrokBinding, replaceSdkOnlyGrokBinding } from './sdkOnlyGrokBinding'
describe('readVerifiedSdkOnlyCodexBinding', () => {
const model = 'gpt-5.6-luna'
@@ -398,4 +400,76 @@ describe('Plugin Workload SDK bootstrap identity', () => {
expect(result.codexBinding).not.toHaveProperty('leaked')
replaceSdkOnlyCodexBinding(null)
})
+
+ it('keeps Grok identity ready while the v3 execution binding is missing', async () => {
+ replaceSdkOnlyGrokBinding(null)
+ const verify = vi.fn()
+ const result = await configurePluginWorkloadSdkBootstrapIdentity(
+ {
+ capabilityFamily: 'promptBridge',
+ provider: 'grok-subscription',
+ model: 'grok-4.6',
+ contractVersion: 3,
+ },
+ { capabilityFamily: 'promptBridge', verify }
+ )
+ expect(result).toMatchObject({
+ configured: true,
+ ready: true,
+ contractVersion: 3,
+ policyReady: false,
+ policyReason: 'execution_binding_missing',
+ bindingReady: false,
+ })
+ expect(result).not.toHaveProperty('codexBinding')
+ expect(verify).not.toHaveBeenCalled()
+ expect(readSdkOnlyGrokBinding()).toBeNull()
+ })
+
+ it('echoes subscriptionBinding and generic ready flags for a verified Grok proof', async () => {
+ const binding = {
+ connectionKey: 'team-grok',
+ catalogRevision: 5,
+ credentialRevision: 2,
+ model: 'grok-4.6',
+ bindingHash: computeGrokPolicyHash({
+ model: 'grok-4.6',
+ catalogRevision: 5,
+ credentialRevision: 2,
+ connectionKey: 'team-grok',
+ }),
+ }
+ const verify = vi.fn().mockResolvedValue({
+ ready: true,
+ contractVersion: 3,
+ provider: 'grok-subscription',
+ model: 'grok-4.6',
+ policyReady: true,
+ policyState: 'active',
+ bindingReady: true,
+ })
+ const result = await configurePluginWorkloadSdkBootstrapIdentity(
+ {
+ capabilityFamily: 'promptBridge',
+ provider: 'grok-subscription',
+ model: 'grok-4.6',
+ contractVersion: 3,
+ subscriptionBinding: binding,
+ },
+ { capabilityFamily: 'promptBridge', verify }
+ )
+ expect(result).toMatchObject({
+ configured: true,
+ ready: true,
+ contractVersion: 3,
+ provider: 'grok-subscription',
+ model: 'grok-4.6',
+ subscriptionBinding: binding,
+ bindingReady: true,
+ })
+ expect(result).not.toHaveProperty('codexBinding')
+ expect(readSdkOnlyGrokBinding()).toEqual(binding)
+ expect(readSdkOnlyCodexBinding()).toBeNull()
+ replaceSdkOnlyGrokBinding(null)
+ })
})
diff --git a/mcp-host/src/pluginWorkloadSdk/bootstrapIdentity.ts b/mcp-host/src/pluginWorkloadSdk/bootstrapIdentity.ts
index 0e801fa8d..b54cf9bab 100644
--- a/mcp-host/src/pluginWorkloadSdk/bootstrapIdentity.ts
+++ b/mcp-host/src/pluginWorkloadSdk/bootstrapIdentity.ts
@@ -8,6 +8,7 @@ import type {
PluginWorkloadSdkClientNotificationsBootstrapProof,
} from './promptBridge/controlApiClient'
import { readVerifiedSdkOnlyCodexBinding, replaceSdkOnlyCodexBinding } from './sdkOnlyCodexBinding'
+import { readVerifiedSdkOnlyGrokBinding, replaceSdkOnlyGrokBinding } from './sdkOnlyGrokBinding'
export interface PluginWorkloadSdkBootstrapIdentityDeps {
/**
@@ -93,10 +94,15 @@ export async function configurePluginWorkloadSdkBootstrapIdentity(
}
// Always integrity-check a supplied binding before the provider protocol
// branch. Request-controlled provider/version must not skip this check.
- const verifiedBinding = readVerifiedSdkOnlyCodexBinding(req.codexBinding, model)
+ const grok = req.provider === 'grok-subscription'
+ const verifiedBinding = grok
+ ? readVerifiedSdkOnlyGrokBinding(req.subscriptionBinding ?? req.codexBinding, model)
+ : readVerifiedSdkOnlyCodexBinding(req.codexBinding ?? req.subscriptionBinding, model)
+ const missingReason = grok ? 'execution_binding_missing' : 'codex_execution_binding_missing'
if (isOauthBrokerProvider(req.provider)) {
if (!verifiedBinding) {
replaceSdkOnlyCodexBinding(null)
+ replaceSdkOnlyGrokBinding(null)
return {
configured: true,
ready: true,
@@ -106,13 +112,23 @@ export async function configurePluginWorkloadSdkBootstrapIdentity(
contractVersion: 3,
policyReady: false,
policyState: 'binding_missing',
- policyReason: 'codex_execution_binding_missing',
- message: 'SDK-only Codex bootstrap requires a live v3 execution binding',
+ policyReason: missingReason,
+ ...(grok ? { bindingReady: false } : {}),
+ message: grok
+ ? 'SDK-only Grok bootstrap requires a live v3 execution binding'
+ : 'SDK-only Codex bootstrap requires a live v3 execution binding',
}
}
- replaceSdkOnlyCodexBinding(verifiedBinding)
+ if (grok) {
+ replaceSdkOnlyCodexBinding(null)
+ replaceSdkOnlyGrokBinding(verifiedBinding)
+ } else {
+ replaceSdkOnlyGrokBinding(null)
+ replaceSdkOnlyCodexBinding(verifiedBinding)
+ }
} else {
replaceSdkOnlyCodexBinding(null)
+ replaceSdkOnlyGrokBinding(null)
}
// The binding must be installed BEFORE this call — `deps.verify` reads the
// live global to build its capabilities request. That ordering means a throw
@@ -125,11 +141,17 @@ export async function configurePluginWorkloadSdkBootstrapIdentity(
try {
proof = deps.verify ? await deps.verify(req.provider, model) : null
} catch (err) {
- if (isOauthBrokerProvider(req.provider)) replaceSdkOnlyCodexBinding(null)
+ if (isOauthBrokerProvider(req.provider)) {
+ replaceSdkOnlyCodexBinding(null)
+ replaceSdkOnlyGrokBinding(null)
+ }
throw err
}
if (deps.verify && !proof) {
- if (isOauthBrokerProvider(req.provider)) replaceSdkOnlyCodexBinding(null)
+ if (isOauthBrokerProvider(req.provider)) {
+ replaceSdkOnlyCodexBinding(null)
+ replaceSdkOnlyGrokBinding(null)
+ }
return {
configured: false,
ready: false,
@@ -140,9 +162,14 @@ export async function configurePluginWorkloadSdkBootstrapIdentity(
if (
isOauthBrokerProvider(req.provider) &&
proof &&
- (proof.codexBindingReady === false || proof.policyReason === 'codex_execution_binding_missing')
+ (proof.codexBindingReady === false ||
+ proof.bindingReady === false ||
+ proof.policyReason === 'codex_execution_binding_missing' ||
+ proof.policyReason === 'execution_binding_missing')
) {
replaceSdkOnlyCodexBinding(null)
+ replaceSdkOnlyGrokBinding(null)
+ const rejectedReason = grok ? 'execution_binding_missing' : 'codex_execution_binding_missing'
return {
configured: true,
ready: true,
@@ -152,9 +179,13 @@ export async function configurePluginWorkloadSdkBootstrapIdentity(
contractVersion: 3,
policyReady: false,
policyState: proof.policyState,
- policyReason: 'codex_execution_binding_missing',
- message: 'Control API rejected the SDK-only Codex execution binding',
- ...(verifiedBinding ? { codexBinding: verifiedBinding } : {}),
+ policyReason: rejectedReason,
+ ...(grok ? { bindingReady: false } : {}),
+ message: grok
+ ? 'Control API rejected the SDK-only Grok execution binding'
+ : 'Control API rejected the SDK-only Codex execution binding',
+ ...(verifiedBinding && grok ? { subscriptionBinding: verifiedBinding } : {}),
+ ...(verifiedBinding && !grok ? { codexBinding: verifiedBinding } : {}),
}
}
deps.onConfigured?.({ provider: req.provider, defaultModel: model })
@@ -182,7 +213,10 @@ export async function configurePluginWorkloadSdkBootstrapIdentity(
...(proof?.clientNotificationsPolicyReason !== undefined
? { clientNotificationsPolicyReason: proof.clientNotificationsPolicyReason }
: {}),
- ...(isOauthBrokerProvider(req.provider) && verifiedBinding
+ ...(isOauthBrokerProvider(req.provider) && verifiedBinding && grok
+ ? { subscriptionBinding: verifiedBinding, bindingReady: true }
+ : {}),
+ ...(isOauthBrokerProvider(req.provider) && verifiedBinding && !grok
? { codexBinding: verifiedBinding }
: {}),
}
diff --git a/mcp-host/src/pluginWorkloadSdk/promptBridge/controlApiClient.ts b/mcp-host/src/pluginWorkloadSdk/promptBridge/controlApiClient.ts
index bb7884a40..f9b53a208 100644
--- a/mcp-host/src/pluginWorkloadSdk/promptBridge/controlApiClient.ts
+++ b/mcp-host/src/pluginWorkloadSdk/promptBridge/controlApiClient.ts
@@ -108,8 +108,10 @@ export interface PluginWorkloadSdkBootstrapProof {
| 'bootstrap_target_mismatch'
| 'policy_not_ready'
| 'codex_execution_binding_missing'
+ | 'execution_binding_missing'
/** Control API attested the live Codex connection against the v3 binding. */
codexBindingReady?: boolean
+ bindingReady?: boolean
/**
* Policy metadata is deliberately optional at identity bootstrap. A recipe
* may be installed and publish an awaiting-policy SDK runtime before an
diff --git a/mcp-host/src/pluginWorkloadSdk/sdkOnlyGrokBinding.ts b/mcp-host/src/pluginWorkloadSdk/sdkOnlyGrokBinding.ts
new file mode 100644
index 000000000..f61f29b4f
--- /dev/null
+++ b/mcp-host/src/pluginWorkloadSdk/sdkOnlyGrokBinding.ts
@@ -0,0 +1,52 @@
+import type { CodexPolicyBinding } from '@clerum/codex-catalog-projection'
+import { computeGrokPolicyHash } from '@clerum/grok-provider-attempt-contract'
+import {
+ type PluginWorkloadSdkCodexBindingProof,
+ isPluginWorkloadSdkCodexBindingProof,
+ sanitizePluginWorkloadSdkCodexBindingProof,
+} from './sdkOnlyCodexBinding'
+
+let current: PluginWorkloadSdkCodexBindingProof | null = null
+
+export function replaceSdkOnlyGrokBinding(
+ next: PluginWorkloadSdkCodexBindingProof | null
+): PluginWorkloadSdkCodexBindingProof | null {
+ current = next
+ return current
+}
+
+export function readSdkOnlyGrokBinding(): PluginWorkloadSdkCodexBindingProof | null {
+ return current
+}
+
+export function sdkOnlyGrokBindingAsPolicy(): CodexPolicyBinding | null {
+ if (!current) return null
+ return {
+ catalogRevision: current.catalogRevision,
+ credentialRevision: current.credentialRevision,
+ connectionKey: current.connectionKey,
+ models: [current.model],
+ }
+}
+
+export function verifySdkOnlyGrokBindingHash(binding: PluginWorkloadSdkCodexBindingProof): boolean {
+ return (
+ binding.bindingHash ===
+ computeGrokPolicyHash({
+ model: binding.model,
+ catalogRevision: binding.catalogRevision,
+ credentialRevision: binding.credentialRevision,
+ connectionKey: binding.connectionKey,
+ })
+ )
+}
+
+export function readVerifiedSdkOnlyGrokBinding(
+ value: unknown,
+ model: string
+): PluginWorkloadSdkCodexBindingProof | null {
+ if (!isPluginWorkloadSdkCodexBindingProof(value)) return null
+ if (value.model !== model) return null
+ if (!verifySdkOnlyGrokBindingHash(value)) return null
+ return sanitizePluginWorkloadSdkCodexBindingProof(value)
+}
diff --git a/mcp-host/src/workflow/types.ts b/mcp-host/src/workflow/types.ts
index 8ca5341e5..e57663089 100644
--- a/mcp-host/src/workflow/types.ts
+++ b/mcp-host/src/workflow/types.ts
@@ -119,6 +119,7 @@ export interface ConfigureResponse {
* `/configure` remains on its legacy response shape.
*/
contractVersion?: 2 | 3
+ bindingReady?: boolean
/**
* Sanitized Codex execution binding echoed on configure v3. Absent for
* non-Codex v2 recipes.
@@ -130,6 +131,13 @@ export interface ConfigureResponse {
model: string
bindingHash: string
}
+ subscriptionBinding?: {
+ connectionKey: string
+ catalogRevision: number
+ credentialRevision: number
+ model: string
+ bindingHash: string
+ }
ready?: boolean
/** Pod/protocol identity is ready even while operator policy is pending. */
policyReady?: boolean
@@ -160,6 +168,13 @@ export interface PluginWorkloadSdkBootstrapRequest {
model: string
bindingHash: string
}
+ subscriptionBinding?: {
+ connectionKey: string
+ catalogRevision: number
+ credentialRevision: number
+ model: string
+ bindingHash: string
+ }
}
// ─── Internal Tools (clerum__*) ──────────────────────────────────────
diff --git a/packages/codex-catalog-projection/index.cjs b/packages/codex-catalog-projection/index.cjs
index e224c243a..e56a6634a 100644
--- a/packages/codex-catalog-projection/index.cjs
+++ b/packages/codex-catalog-projection/index.cjs
@@ -391,6 +391,41 @@ function toEligiblePolicyBinding(cm, connectionKey, model) {
}
}
+function toEligibleGrokPolicyBinding(cm, connectionKey, model) {
+ const key = assignedCodexConnectionKey(connectionKey)
+ const trimmedModel = typeof model === 'string' ? model.trim() : ''
+ if (key === CODEX_UNASSIGNED_CONNECTION_KEY) {
+ return { binding: null, eligibility: 'ineligible', reason: 'unassigned' }
+ }
+ if (!trimmedModel) {
+ return { binding: null, eligibility: 'ineligible', reason: 'model_missing' }
+ }
+ const snapshot = parseGrokAllowedModelsSnapshot(cm, key)
+ const projection = projectGrokExecution(
+ { model: { provider: GROK_PROVIDER, name: trimmedModel } },
+ snapshot
+ )
+ if (projection.eligibility !== 'eligible') {
+ return { binding: null, eligibility: projection.eligibility, reason: projection.reason }
+ }
+ if (
+ !Number.isInteger(snapshot.catalogRevision) ||
+ !Number.isInteger(snapshot.connectionRevision)
+ ) {
+ return { binding: null, eligibility: 'ineligible', reason: 'revision_missing' }
+ }
+ return {
+ binding: {
+ connectionKey: key,
+ catalogRevision: snapshot.catalogRevision,
+ credentialRevision: snapshot.connectionRevision,
+ model: trimmedModel,
+ },
+ eligibility: 'eligible',
+ reason: 'eligible',
+ }
+}
+
function toGrokPolicyBinding(cm, connectionKey) {
const key = assignedCodexConnectionKey(connectionKey)
if (!cm || key === CODEX_UNASSIGNED_CONNECTION_KEY) return null
@@ -575,5 +610,6 @@ module.exports = {
projectGrokExecution,
toPolicyBinding,
toGrokPolicyBinding,
+ toEligibleGrokPolicyBinding,
toEligiblePolicyBinding,
}
diff --git a/packages/codex-catalog-projection/index.d.ts b/packages/codex-catalog-projection/index.d.ts
index e93220930..82c084520 100644
--- a/packages/codex-catalog-projection/index.d.ts
+++ b/packages/codex-catalog-projection/index.d.ts
@@ -148,6 +148,11 @@ export declare function toGrokPolicyBinding(
cm: CodexConfigMapView | undefined | null,
connectionKey?: string
): CodexPolicyBinding | null
+export declare function toEligibleGrokPolicyBinding(
+ cm: CodexConfigMapView | undefined | null,
+ connectionKey: string | undefined,
+ model: string
+): CodexEligiblePolicyBindingProjection
/**
* Structural revision view for the Host chat reader (`configStore`). It does
* NOT decide eligibility: a transiently `unavailable`/`reauth-required`
diff --git a/packages/codex-catalog-projection/index.test.cjs b/packages/codex-catalog-projection/index.test.cjs
index d2656f80f..d533588f0 100644
--- a/packages/codex-catalog-projection/index.test.cjs
+++ b/packages/codex-catalog-projection/index.test.cjs
@@ -545,3 +545,21 @@ test('projectGrokExecution mints llm:grok:execute only for an eligible Grok targ
assert.deepEqual(staticOnly.derivedScopes, [])
assert.equal(staticOnly.requiresGrokProxyEgress, false)
})
+
+test('toEligibleGrokPolicyBinding mints only for an assigned eligible Grok model', () => {
+ const cm = grokView('team-grok', ['grok-4.6'])
+ const eligible = projection.toEligibleGrokPolicyBinding(cm, 'team-grok', 'grok-4.6')
+ assert.equal(eligible.eligibility, 'eligible')
+ assert.deepEqual(eligible.binding, {
+ connectionKey: 'team-grok',
+ catalogRevision: 5,
+ credentialRevision: 2,
+ model: 'grok-4.6',
+ })
+ assert.equal(projection.toEligibleGrokPolicyBinding(cm, 'unassigned', 'grok-4.6').reason, 'unassigned')
+ assert.equal(projection.toEligibleGrokPolicyBinding(cm, '', 'grok-4.6').reason, 'unassigned')
+ assert.equal(
+ projection.toEligibleGrokPolicyBinding(cm, 'team-grok', 'missing-model').binding,
+ null
+ )
+})
diff --git a/scripts/tests/test-codex-subscription-t0.sh b/scripts/tests/test-codex-subscription-t0.sh
index 893588383..2bbcbbe32 100755
--- a/scripts/tests/test-codex-subscription-t0.sh
+++ b/scripts/tests/test-codex-subscription-t0.sh
@@ -229,6 +229,7 @@ run_group "control-api" "control-api" \
"test/services.codexSubscriptionOAuth.test.ts" \
"test/services.codexSubscriptionCatalog.test.ts" \
"test/services.llmProviderAttemptAuthorizer.test.ts" \
+ "test/services.llmProviderAttemptAuthorizer.grok.test.ts" \
"test/services.llmProviderAttemptTicket.test.ts" \
"test/services.llmProviderAttemptRedemption.test.ts" \
"test/services.llmProviderAttemptFinalization.test.ts" \
@@ -286,6 +287,8 @@ run_group "workflow-recipes" "workflow-recipes" \
"src/workflow/llmAllowedModelsSnapshot.test.ts" \
"src/workflow/networkPolicyFactory.codex.test.ts" \
"src/workflow/sdkOnlyCodexBinding.test.ts" \
+ "src/workflow/sdkOnlyGrokBinding.test.ts" \
+ "src/workflow/pluginWorkloadSdkProvisioner.codexPolicy.test.ts" \
"src/reconciler/pluginWorkloadSdkValidator.test.ts" \
"tests/unit/workflow/modelConfigHandler.test.ts" \
"tests/unit/workflow/modelConfigHandler.pluginSdkBroker.test.ts"
@@ -298,7 +301,8 @@ run_group "control-ui" "control-ui" \
"lib/__tests__/llmCredentialSelect.test.ts" \
"components/__tests__/HostWizard.test.tsx" \
"components/__tests__/HostDetailsPage.identity.test.tsx" \
- "components/__tests__/RecipeEditor.test.tsx"
+ "components/__tests__/RecipeEditor.test.tsx" \
+ "components/__tests__/PluginWorkloadSdkPage.test.tsx"
node_major=$(node --version | sed -n 's/^v\([0-9][0-9]*\).*/\1/p')
if [[ "${node_major}" != "24" ]]; then
diff --git a/scripts/tests/test-grok-subscription-t0.sh b/scripts/tests/test-grok-subscription-t0.sh
index 72e1e93af..b9e6c3073 100755
--- a/scripts/tests/test-grok-subscription-t0.sh
+++ b/scripts/tests/test-grok-subscription-t0.sh
@@ -87,17 +87,59 @@ require_file grok-llm-proxy/test/originPolicy.test.ts
require_file control-api/test/services.grokSubscriptionOAuth.test.ts
require_file control-api/test/services.grokProviderAttemptRedemption.test.ts
require_file control-api/test/db.grokSubscriptionMigration.test.ts
+require_file control-api/test/services.llmProviderAttemptAuthorizer.grok.test.ts
+require_file control-api/test/subscriptionGrantIdentity.test.ts
require_file scripts/tests/test-grok-llm-proxy-deploy-contract.sh
require_file tests/e2e/fixtures/grok-subscription/sanitized-upstream-contract.json
+require_file workflow-recipes/src/workflow/codexRecipeVerdict.test.ts
+require_file workflow-recipes/src/workflow/sdkOnlyGrokBinding.test.ts
+require_file mcp-host/src/pluginWorkloadSdk/bootstrapIdentity.test.ts
+require_file packages/codex-catalog-projection/index.test.cjs
+require_file control-ui/components/__tests__/PluginWorkloadSdkPage.test.tsx
+
+expected_device_url='https://auth.x.ai/oauth2/device/code'
+expected_token_url='https://auth.x.ai/oauth2/token'
+expected_client_id='b1a00492-073a-47ea-816f-4c329264a828'
+api_device_url="$(
+ sed -n "s/^export const GROK_OAUTH_DEVICE_URL = '\\(.*\\)'$/\\1/p" \
+ "${ROOT}/control-api/src/services/grokSubscriptionOAuth.ts"
+)"
+api_token_url="$(
+ sed -n "s/^export const GROK_OAUTH_TOKEN_URL = '\\(.*\\)'$/\\1/p" \
+ "${ROOT}/control-api/src/services/grokSubscriptionOAuth.ts"
+)"
+api_client_id="$(
+ sed -n "s/^export const GROK_OAUTH_DEFAULT_CLIENT_ID = '\\(.*\\)'$/\\1/p" \
+ "${ROOT}/control-api/src/services/grokSubscriptionOAuth.ts"
+)"
+if [[ "${api_device_url}" == "${expected_device_url}" &&
+ "${api_token_url}" == "${expected_token_url}" &&
+ "${api_client_id}" == "${expected_client_id}" ]]; then
+ pass "Grok OAuth origin/client lock"
+else
+ fail "Grok OAuth origin/client lock (device=${api_device_url:-missing} token=${api_token_url:-missing} client=${api_client_id:-missing})"
+fi
run_group "grok-provider-attempt-contract" \
bash -lc "cd '${ROOT}/packages/grok-provider-attempt-contract' && node --test index.test.cjs"
+run_group "grok-catalog-projection" \
+ bash -lc "cd '${ROOT}/packages/codex-catalog-projection' && node --test index.test.cjs"
+
run_group "grok-llm-proxy freeze+origin" \
bash -lc "cd '${ROOT}/grok-llm-proxy' && npx vitest run test/contractFreeze.test.ts test/originPolicy.test.ts --no-file-parallelism"
-run_group "control-api grok grant/oauth/redeem" \
- bash -lc "cd '${ROOT}/control-api' && npx vitest run test/db.grokSubscriptionMigration.test.ts test/services.grokSubscriptionConnection.test.ts test/services.grokSubscriptionOAuth.test.ts test/services.grokSubscriptionCatalog.test.ts test/services.grokProviderAttemptRedemption.test.ts --no-file-parallelism"
+run_group "control-api grok grant/oauth/redeem/authorize" \
+ bash -lc "cd '${ROOT}/control-api' && npx vitest run test/db.grokSubscriptionMigration.test.ts test/services.grokSubscriptionConnection.test.ts test/services.grokSubscriptionOAuth.test.ts test/services.grokSubscriptionCatalog.test.ts test/services.grokProviderAttemptRedemption.test.ts test/services.llmProviderAttemptAuthorizer.grok.test.ts test/subscriptionGrantIdentity.test.ts --no-file-parallelism"
+
+run_group "workflow-recipes grok SDK" \
+ bash -lc "cd '${ROOT}/workflow-recipes' && npx vitest run src/workflow/codexRecipeVerdict.test.ts src/workflow/sdkOnlyGrokBinding.test.ts src/workflow/pluginWorkloadSdkProvisioner.codexPolicy.test.ts src/reconciler/pluginWorkloadSdkValidator.test.ts tests/unit/workflow/modelConfigHandler.pluginSdkBroker.test.ts --no-file-parallelism"
+
+run_group "mcp-host grok bootstrap" \
+ bash -lc "cd '${ROOT}/mcp-host' && npx vitest run src/pluginWorkloadSdk/bootstrapIdentity.test.ts --no-file-parallelism"
+
+run_group "control-ui grok SDK picker" \
+ bash -lc "cd '${ROOT}/control-ui' && npx vitest run components/__tests__/PluginWorkloadSdkPage.test.tsx --no-file-parallelism"
if ! bash "${ROOT}/scripts/tests/test-grok-llm-proxy-deploy-contract.sh"; then
fail "grok-llm-proxy deploy contract"
@@ -106,7 +148,7 @@ else
pass "grok-llm-proxy deploy contract"
fi
-if [[ "$GROUPS_RUN" -lt 4 ]]; then
+if [[ "$GROUPS_RUN" -lt 8 ]]; then
fail "T0 ran too few groups (${GROUPS_RUN})"
fi
diff --git a/workflow-recipes/package-lock.json b/workflow-recipes/package-lock.json
index a412b033a..a1580c706 100644
--- a/workflow-recipes/package-lock.json
+++ b/workflow-recipes/package-lock.json
@@ -1,16 +1,17 @@
{
"name": "workload-recipes-controller",
- "version": "0.1.353",
+ "version": "0.1.354",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "workload-recipes-controller",
- "version": "0.1.353",
+ "version": "0.1.354",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@aws-sdk/client-s3": "^3.1009.0",
"@clerum/codex-catalog-projection": "file:../packages/codex-catalog-projection",
+ "@clerum/grok-provider-attempt-contract": "file:../packages/grok-provider-attempt-contract",
"@clerum/image-policy": "file:../packages/image-policy",
"@clerum/llm-provider-attempt-contract": "file:../packages/llm-provider-attempt-contract",
"@clerum/llm-providers": "file:../packages/llm-providers",
@@ -45,6 +46,11 @@
"version": "0.1.0",
"license": "MIT"
},
+ "../packages/grok-provider-attempt-contract": {
+ "name": "@clerum/grok-provider-attempt-contract",
+ "version": "0.1.0",
+ "license": "MIT"
+ },
"../packages/image-policy": {
"name": "@clerum/image-policy",
"version": "0.1.0",
@@ -587,6 +593,10 @@
"resolved": "../packages/codex-catalog-projection",
"link": true
},
+ "node_modules/@clerum/grok-provider-attempt-contract": {
+ "resolved": "../packages/grok-provider-attempt-contract",
+ "link": true
+ },
"node_modules/@clerum/image-policy": {
"resolved": "../packages/image-policy",
"link": true
diff --git a/workflow-recipes/package.json b/workflow-recipes/package.json
index 871917bad..a8543d2ce 100644
--- a/workflow-recipes/package.json
+++ b/workflow-recipes/package.json
@@ -1,6 +1,6 @@
{
"name": "workload-recipes-controller",
- "version": "0.1.353",
+ "version": "0.1.354",
"description": "Workload Recipes Controller (WRC) - WorkloadRecipe lifecycle management and MCP server interface",
"main": "dist/main.js",
"engines": {
@@ -29,6 +29,7 @@
"dependencies": {
"@aws-sdk/client-s3": "^3.1009.0",
"@clerum/codex-catalog-projection": "file:../packages/codex-catalog-projection",
+ "@clerum/grok-provider-attempt-contract": "file:../packages/grok-provider-attempt-contract",
"@clerum/image-policy": "file:../packages/image-policy",
"@clerum/llm-provider-attempt-contract": "file:../packages/llm-provider-attempt-contract",
"@clerum/llm-providers": "file:../packages/llm-providers",
diff --git a/workflow-recipes/src/reconciler/pluginWorkloadSdkValidator.test.ts b/workflow-recipes/src/reconciler/pluginWorkloadSdkValidator.test.ts
index b7281d38b..8b30b5c04 100644
--- a/workflow-recipes/src/reconciler/pluginWorkloadSdkValidator.test.ts
+++ b/workflow-recipes/src/reconciler/pluginWorkloadSdkValidator.test.ts
@@ -594,6 +594,52 @@ describe('buildPluginWorkloadSdkStatus', () => {
})
})
+ it('blocks Validated when the Grok execution binding is missing', () => {
+ const projection = buildPluginWorkloadSdkStatus({
+ spec: baseSpec(
+ { promptBridge: {} },
+ { agent: { provider: 'grok-subscription', model: 'grok-4.6' } }
+ ),
+ existingConditions: undefined,
+ phase: 'active',
+ featureFlagEnabled: true,
+ bootstrapProof: {
+ ready: true,
+ contractVersion: 3,
+ podUid: 'pod-uid-1',
+ provider: 'grok-subscription',
+ model: 'grok-4.6',
+ policyReady: false,
+ policyState: 'binding_missing',
+ policyReason: 'execution_binding_missing',
+ verifiedAt: NOW,
+ },
+ now: NOW,
+ })
+ expect(projection.conditions).toEqual([
+ {
+ type: PLUGIN_WORKLOAD_SDK_CONDITION_TYPE,
+ status: 'False',
+ reason: 'PolicyNotConfigured',
+ message: 'Plugin Workload SDK promptBridge policy is not ready (execution_binding_missing)',
+ lastTransitionTime: NOW,
+ },
+ {
+ type: PLUGIN_WORKLOAD_SDK_POLICY_PENDING_CONDITION_TYPE,
+ status: 'True',
+ reason: 'execution_binding_missing',
+ message: 'Plugin Workload SDK promptBridge policy is not ready (execution_binding_missing)',
+ lastTransitionTime: NOW,
+ },
+ ])
+ expect(projection.capability).toMatchObject({
+ state: 'awaiting_policy',
+ bootstrapContractVersion: 3,
+ bootstrapProvider: 'grok-subscription',
+ validatedAt: null,
+ })
+ })
+
it('names a stale Codex bootstrap contract when the binding proof is absent', () => {
const projection = buildPluginWorkloadSdkStatus({
spec: baseSpec(
diff --git a/workflow-recipes/src/reconciler/pluginWorkloadSdkValidator.ts b/workflow-recipes/src/reconciler/pluginWorkloadSdkValidator.ts
index 3d869d7fd..7f71c5c67 100644
--- a/workflow-recipes/src/reconciler/pluginWorkloadSdkValidator.ts
+++ b/workflow-recipes/src/reconciler/pluginWorkloadSdkValidator.ts
@@ -193,6 +193,13 @@ export interface PluginWorkloadSdkBootstrapProofInput {
model: string
bindingHash: string
}
+ subscriptionBinding?: {
+ connectionKey: string
+ catalogRevision: number
+ credentialRevision: number
+ model: string
+ bindingHash: string
+ }
provider?: string
model?: string
policyReady?: boolean
@@ -218,8 +225,17 @@ function promptBridgePolicyPendingReason(
codexBindingPending: boolean
): string {
if (codexBindingPending) {
- if (bootstrapProof?.contractVersion !== 3) return 'codex_bootstrap_contract_stale'
- return bootstrapProof.policyReason ?? 'codex_execution_binding_missing'
+ if (bootstrapProof?.contractVersion !== 3) {
+ return bootstrapProof?.provider === 'grok-subscription'
+ ? 'execution_binding_missing'
+ : 'codex_bootstrap_contract_stale'
+ }
+ return (
+ bootstrapProof.policyReason ??
+ (bootstrapProof.provider === 'grok-subscription'
+ ? 'execution_binding_missing'
+ : 'codex_execution_binding_missing')
+ )
}
return bootstrapProof?.policyReason ?? bootstrapProof?.policyState ?? 'unknown'
}
@@ -366,9 +382,20 @@ export function buildPluginWorkloadSdkStatus(args: {
(bootstrapProof.policyReason === 'codex_execution_binding_missing' ||
bootstrapProof.contractVersion !== 3 ||
!bootstrapProof.codexBinding)
- if (policyPending || clientNotificationsPolicyPending || codexBindingPending) {
+ const grokBindingPending =
+ promptBridge &&
+ bootstrapProof?.provider === 'grok-subscription' &&
+ (bootstrapProof.policyReason === 'execution_binding_missing' ||
+ bootstrapProof.contractVersion !== 3 ||
+ !bootstrapProof.subscriptionBinding)
+ if (
+ policyPending ||
+ clientNotificationsPolicyPending ||
+ codexBindingPending ||
+ grokBindingPending
+ ) {
const family =
- promptBridge && (policyPending || codexBindingPending)
+ promptBridge && (policyPending || codexBindingPending || grokBindingPending)
? 'promptBridge'
: 'clientNotifications'
const policyReason =
@@ -376,7 +403,7 @@ export function buildPluginWorkloadSdkStatus(args: {
? (bootstrapProof?.clientNotificationsPolicyReason ??
bootstrapProof?.clientNotificationsPolicyState ??
'unknown')
- : promptBridgePolicyPendingReason(bootstrapProof, codexBindingPending)
+ : promptBridgePolicyPendingReason(bootstrapProof, codexBindingPending || grokBindingPending)
const message =
policyReason === 'grant_missing'
? `Plugin Workload SDK ${family} is awaiting an operator grant`
diff --git a/workflow-recipes/src/workflow/codexRecipeVerdict.test.ts b/workflow-recipes/src/workflow/codexRecipeVerdict.test.ts
index 86fdef352..c417e120c 100644
--- a/workflow-recipes/src/workflow/codexRecipeVerdict.test.ts
+++ b/workflow-recipes/src/workflow/codexRecipeVerdict.test.ts
@@ -1,5 +1,6 @@
import { describe, expect, it } from 'vitest'
import type { CodexConfigMapView } from '@clerum/codex-catalog-projection'
+import { computeGrokPolicyHash } from '@clerum/grok-provider-attempt-contract'
import { computeCodexPolicyHash } from '@clerum/llm-provider-attempt-contract'
import type { WorkflowRecipeSpec } from '../types'
import {
@@ -30,6 +31,8 @@ const MODEL = 'gpt-5.6-luna'
const GRANT = 'team-plus'
const RECIPE = 'notify-app'
const UNASSIGNED = 'unassigned'
+const GROK_MODEL = 'grok-4.6'
+const GROK_GRANT = 'team-grok'
const codexSpec = (): WorkflowRecipeSpec =>
({ agent: { provider: 'codex-subscription', model: MODEL } }) as unknown as WorkflowRecipeSpec
@@ -222,6 +225,92 @@ describe('projectCodexRecipeVerdict', () => {
if (v.projection.eligibility === 'uncertain') {
expect(`${name}:${v.hostBinding === null}`).toBe(`${name}:true`)
}
+ if (v.grokBinding !== null) {
+ expect(`${name}:${v.grokProjection.eligibility}`).toBe(`${name}:eligible`)
+ expect(`${name}:${v.provenance}`).toBe(`${name}:authoritative`)
+ }
+ if (v.grokProjection.eligibility === 'uncertain') {
+ expect(`${name}:${v.grokBinding === null}`).toBe(`${name}:true`)
+ }
}
})
})
+
+const grokSpec = (): WorkflowRecipeSpec =>
+ ({ agent: { provider: 'grok-subscription', model: GROK_MODEL } }) as unknown as WorkflowRecipeSpec
+
+function eligibleGrokConfigMap(): CodexConfigMapView {
+ return {
+ metadata: {
+ annotations: {
+ 'clerum.io/grok-enabled': 'true',
+ 'clerum.io/grok-connection-status': 'connected',
+ 'clerum.io/grok-connections': JSON.stringify({
+ [GROK_GRANT]: {
+ status: 'connected',
+ catalogRevision: 5,
+ connectionRevision: 2,
+ models: [GROK_MODEL],
+ },
+ }),
+ },
+ },
+ data: {},
+ }
+}
+
+describe('projectCodexRecipeVerdict Grok mint', () => {
+ it('mints a Grok binding even when the Codex projection is ineligible', () => {
+ const v = projectCodexRecipeVerdict({
+ ownSpec: grokSpec(),
+ context: context({ connectionKey: UNASSIGNED, grokConnectionKey: GROK_GRANT }),
+ hostAgent: { provider: 'grok-subscription', model: GROK_MODEL },
+ view: viewFrom(eligibleGrokConfigMap()),
+ })
+ expect(v.projection.eligibility).not.toBe('eligible')
+ expect(v.hostBinding).toBeNull()
+ expect(v.grokProjection.eligibility).toBe('eligible')
+ expect(v.grokBinding).toEqual({
+ connectionKey: GROK_GRANT,
+ catalogRevision: 5,
+ credentialRevision: 2,
+ model: GROK_MODEL,
+ bindingHash: computeGrokPolicyHash({
+ model: GROK_MODEL,
+ catalogRevision: 5,
+ credentialRevision: 2,
+ connectionKey: GROK_GRANT,
+ }),
+ })
+ })
+
+ it('withholds Grok scope and binding when provenance is uncertain', () => {
+ const v = projectCodexRecipeVerdict({
+ ownSpec: grokSpec(),
+ context: context({
+ runtimeScopeRecipeName: 'parent-recipe',
+ parentSpec: null,
+ connectionKey: UNASSIGNED,
+ grokConnectionKey: GROK_GRANT,
+ }),
+ hostAgent: { provider: 'grok-subscription', model: GROK_MODEL },
+ view: viewFrom(eligibleGrokConfigMap()),
+ })
+ expect(v.grokProjection.eligibility).toBe('uncertain')
+ expect(v.grokProjection.reason).toBe('provenance_uncertain')
+ expect(v.grokProjection.requiresGrokProxyEgress).toBe(false)
+ expect(v.grokProjection.derivedScopes).toEqual([])
+ expect(v.grokBinding).toBeNull()
+ })
+
+ it('does not mint a Grok binding for an unassigned Grok grant', () => {
+ const v = projectCodexRecipeVerdict({
+ ownSpec: grokSpec(),
+ context: context({ connectionKey: UNASSIGNED, grokConnectionKey: UNASSIGNED }),
+ hostAgent: { provider: 'grok-subscription', model: GROK_MODEL },
+ view: viewFrom(eligibleGrokConfigMap()),
+ })
+ expect(v.grokBinding).toBeNull()
+ expect(v.grokBindingReason).toBe('unassigned')
+ })
+})
diff --git a/workflow-recipes/src/workflow/codexRecipeVerdict.ts b/workflow-recipes/src/workflow/codexRecipeVerdict.ts
index 5cfd9b9b5..baa9f9b94 100644
--- a/workflow-recipes/src/workflow/codexRecipeVerdict.ts
+++ b/workflow-recipes/src/workflow/codexRecipeVerdict.ts
@@ -4,9 +4,11 @@ import {
type CodexCatalogSnapshot,
type CodexConfigMapView,
type CodexExecutionProjection,
+ GROK_PROVIDER,
parseGrokAllowedModelsSnapshot,
projectGrokExecution,
snapshotForAssignedCodexGrant,
+ toEligibleGrokPolicyBinding,
toEligiblePolicyBinding,
} from '@clerum/codex-catalog-projection'
import type { WorkflowRecipeSpec } from '../types'
@@ -20,6 +22,7 @@ import {
type PluginWorkloadSdkCodexBindingProof,
mintSdkOnlyCodexBindingProof,
} from './sdkOnlyCodexBinding'
+import { mintSdkOnlyGrokBindingProof } from './sdkOnlyGrokBinding'
/*
* ONE Codex verdict per reconcile pass.
@@ -94,6 +97,8 @@ export type CodexRecipeVerdict = {
readonly hostBinding: PluginWorkloadSdkCodexBindingProof | null
readonly hostBindingReason: string
readonly grokProjection: CodexExecutionProjection & { requiresGrokProxyEgress: boolean }
+ readonly grokBinding: PluginWorkloadSdkCodexBindingProof | null
+ readonly grokBindingReason: string
}
export function projectCodexRecipeVerdict(input: {
@@ -122,60 +127,127 @@ export function projectCodexRecipeVerdict(input: {
const projection = projectRecipeCodexExecution(resolved.spec, snapshot, resolved.provenance)
const grokKey = context.grokConnectionKey ?? CODEX_UNASSIGNED_CONNECTION_KEY
const grokSnapshot = parseGrokAllowedModelsSnapshot(view.configMap, grokKey)
- const grokProjection = projectGrokExecution(recipeToCodexHostSpec(resolved.spec), grokSnapshot)
+ const grokRaw = projectGrokExecution(recipeToCodexHostSpec(resolved.spec), grokSnapshot)
+ const grokProjection =
+ resolved.provenance === 'authoritative'
+ ? grokRaw
+ : {
+ ...grokRaw,
+ eligibleTargets: [],
+ derivedScopes: [],
+ requiresGrokProxyEgress: false,
+ eligibility: 'uncertain' as const,
+ reason: 'provenance_uncertain',
+ }
- const base = {
+ const hostBinding = mintCodexHostBinding({
+ hostAgent: input.hostAgent,
+ connectionKey: context.connectionKey,
+ view,
+ projection,
+ log: input.log,
+ })
+ const grokBinding = mintGrokHostBinding({
+ hostAgent: input.hostAgent,
+ grokKey,
+ view,
+ grokProjection,
+ log: input.log,
+ })
+
+ if (
+ projection.eligibility === 'uncertain' &&
+ resolved.provenance !== 'authoritative' &&
+ input.hostAgent?.provider === CODEX_PROVIDER
+ ) {
+ input.log?.warn('Codex provenance is undecidable; withholding scope and binding', {
+ recipeName: context.recipeName,
+ connectionKey: context.connectionKey,
+ provenanceReason: resolved.reason,
+ reason: projection.reason,
+ })
+ }
+
+ return {
provenance: resolved.provenance,
provenanceReason: resolved.reason,
connectionKey: context.connectionKey,
projection,
grokProjection,
- } as const
-
- if (projection.eligibility !== 'eligible') {
- // Warn ONLY for a recipe that actually targets Codex, and
- // only when the doubt is about provenance. An unreadable ConfigMap already
- // produces three warns in `refreshCodexSnapshot`, and it makes EVERY recipe
- // uncertain — including those with no Codex target — because the shared
- // projection checks `snapshotError` before it checks whether the spec has
- // any Codex target at all. Warning there buried the case this line exists
- // to surface: a recipe wedged in awaiting_policy by a stray parent label.
- if (
- projection.eligibility === 'uncertain' &&
- resolved.provenance !== 'authoritative' &&
- input.hostAgent?.provider === CODEX_PROVIDER
- ) {
- input.log?.warn('Codex provenance is undecidable; withholding scope and binding', {
- recipeName: context.recipeName,
- connectionKey: context.connectionKey,
- provenanceReason: resolved.reason,
- reason: projection.reason,
- })
- }
- return { ...base, hostBinding: null, hostBindingReason: projection.reason }
+ hostBinding: hostBinding.binding,
+ hostBindingReason: hostBinding.reason,
+ grokBinding: grokBinding.binding,
+ grokBindingReason: grokBinding.reason,
}
+}
+function mintCodexHostBinding(input: {
+ hostAgent: { provider: string; model: string } | undefined
+ connectionKey: string
+ view: CodexAllowlistView
+ projection: CodexExecutionProjection
+ log?: { debug(msg: string, fields?: Record<string, unknown>): void }
+}): { binding: PluginWorkloadSdkCodexBindingProof | null; reason: string } {
+ if (input.projection.eligibility !== 'eligible') {
+ return { binding: null, reason: input.projection.reason }
+ }
if (!input.hostAgent || input.hostAgent.provider !== CODEX_PROVIDER) {
- return { ...base, hostBinding: null, hostBindingReason: 'host_agent_not_codex' }
+ return { binding: null, reason: 'host_agent_not_codex' }
}
-
- // Reached only past the provenance + eligibility gate above, and re-parsing
- // the SAME captured ConfigMap deterministically: a derivation of this
- // verdict, not a second source of truth.
- const { binding, reason } = toEligiblePolicyBinding(
- view.configMap,
- context.connectionKey,
+ const minted = toEligiblePolicyBinding(
+ input.view.configMap,
+ input.connectionKey,
input.hostAgent.model
)
- if (!binding || binding.catalogRevision < 1 || binding.credentialRevision < 1) {
- const withheld = binding ? 'revision_out_of_range' : reason
+ if (
+ !minted.binding ||
+ minted.binding.catalogRevision < 1 ||
+ minted.binding.credentialRevision < 1
+ ) {
+ const withheld = minted.binding ? 'revision_out_of_range' : minted.reason
input.log?.debug('Codex execution binding withheld', {
- recipeName: context.recipeName,
model: input.hostAgent.model,
- connectionKey: context.connectionKey,
+ connectionKey: input.connectionKey,
+ reason: withheld,
+ })
+ return { binding: null, reason: withheld }
+ }
+ return { binding: mintSdkOnlyCodexBindingProof(minted.binding), reason: minted.reason }
+}
+
+function mintGrokHostBinding(input: {
+ hostAgent: { provider: string; model: string } | undefined
+ grokKey: string
+ view: CodexAllowlistView
+ grokProjection: CodexExecutionProjection
+ log?: { debug(msg: string, fields?: Record<string, unknown>): void }
+}): { binding: PluginWorkloadSdkCodexBindingProof | null; reason: string } {
+ if (input.grokKey === CODEX_UNASSIGNED_CONNECTION_KEY) {
+ return { binding: null, reason: 'unassigned' }
+ }
+ if (input.grokProjection.eligibility !== 'eligible') {
+ return { binding: null, reason: input.grokProjection.reason }
+ }
+ if (!input.hostAgent || input.hostAgent.provider !== GROK_PROVIDER) {
+ return { binding: null, reason: 'host_agent_not_grok' }
+ }
+ const minted = toEligibleGrokPolicyBinding(
+ input.view.configMap,
+ input.grokKey,
+ input.hostAgent.model
+ )
+ if (
+ !minted.binding ||
+ minted.binding.catalogRevision < 1 ||
+ minted.binding.credentialRevision < 1
+ ) {
+ const withheld = minted.binding ? 'revision_out_of_range' : minted.reason
+ input.log?.debug('Grok execution binding withheld', {
+ model: input.hostAgent.model,
+ connectionKey: input.grokKey,
reason: withheld,
})
- return { ...base, hostBinding: null, hostBindingReason: withheld }
+ return { binding: null, reason: withheld }
}
- return { ...base, hostBinding: mintSdkOnlyCodexBindingProof(binding), hostBindingReason: reason }
+ return { binding: mintSdkOnlyGrokBindingProof(minted.binding), reason: minted.reason }
}
diff --git a/workflow-recipes/src/workflow/httpMcpHostClient.ts b/workflow-recipes/src/workflow/httpMcpHostClient.ts
index d9874cb1b..f4ad52ff5 100644
--- a/workflow-recipes/src/workflow/httpMcpHostClient.ts
+++ b/workflow-recipes/src/workflow/httpMcpHostClient.ts
@@ -69,6 +69,13 @@ export class HttpMcpHostClient implements McpHostClient {
model: string
bindingHash: string
} | null
+ subscriptionBinding?: {
+ connectionKey: string
+ catalogRevision: number
+ credentialRevision: number
+ model: string
+ bindingHash: string
+ } | null
}
): Promise<{ status: number; body: Record<string, unknown> }> {
const url = `${endpoint}${PLUGIN_SDK_BOOTSTRAP_PATH}`
diff --git a/workflow-recipes/src/workflow/modelConfigHandler.ts b/workflow-recipes/src/workflow/modelConfigHandler.ts
index de1e97aab..5269ca283 100644
--- a/workflow-recipes/src/workflow/modelConfigHandler.ts
+++ b/workflow-recipes/src/workflow/modelConfigHandler.ts
@@ -22,6 +22,7 @@ import {
} from '@clerum/llm-providers'
import { createLogger } from '../observability/logger'
import { readVerifiedSdkOnlyCodexBinding } from './sdkOnlyCodexBinding'
+import { readVerifiedSdkOnlyGrokBinding } from './sdkOnlyGrokBinding'
// ─── Types ──────────────────────────────────────────────────────────────
@@ -265,7 +266,12 @@ export class ModelConfigHandler {
...(model ? { model } : {}),
...(provider === 'codex-subscription'
? { contractVersion: 3, ...(codexBinding ? { codexBinding } : {}) }
- : { contractVersion: 2 }),
+ : provider === 'grok-subscription'
+ ? {
+ contractVersion: 3,
+ ...(codexBinding ? { subscriptionBinding: codexBinding } : {}),
+ }
+ : { contractVersion: 2 }),
}
)
if (result.status >= 400) {
@@ -277,7 +283,8 @@ export class ModelConfigHandler {
typeof result.body.policyReady === 'boolean' &&
typeof result.body.policyState === 'string'
: isBootstrapIdentityProof(result.body)
- const expectedContractVersion = provider === 'codex-subscription' ? 3 : 2
+ const expectedContractVersion =
+ provider === 'codex-subscription' || provider === 'grok-subscription' ? 3 : 2
if (
result.body.configured !== true ||
result.body.ready !== true ||
@@ -320,6 +327,9 @@ export class ModelConfigHandler {
const verifiedCodexBinding = model
? readVerifiedSdkOnlyCodexBinding(result.body.codexBinding, model)
: null
+ const verifiedGrokBinding = model
+ ? readVerifiedSdkOnlyGrokBinding(result.body.subscriptionBinding, model)
+ : null
return {
status: 202,
body: {
@@ -330,6 +340,7 @@ export class ModelConfigHandler {
contractVersion: expectedContractVersion,
capabilityFamily,
...(verifiedCodexBinding ? { codexBinding: verifiedCodexBinding } : {}),
+ ...(verifiedGrokBinding ? { subscriptionBinding: verifiedGrokBinding } : {}),
...(typeof result.body.policyReady === 'boolean'
? { policyReady: result.body.policyReady }
: {}),
@@ -780,7 +791,8 @@ function mcpHostConfigureRejected(result: {
}
function isBootstrapIdentityProof(body: Record<string, unknown>): boolean {
- const expectedVersion = body.provider === 'codex-subscription' ? 3 : 2
+ const expectedVersion =
+ body.provider === 'codex-subscription' || body.provider === 'grok-subscription' ? 3 : 2
return (
body.configured === true &&
body.ready === true &&
diff --git a/workflow-recipes/src/workflow/pluginWorkloadSdkProvisioner.codexPolicy.test.ts b/workflow-recipes/src/workflow/pluginWorkloadSdkProvisioner.codexPolicy.test.ts
index 143243d62..4d95b7625 100644
--- a/workflow-recipes/src/workflow/pluginWorkloadSdkProvisioner.codexPolicy.test.ts
+++ b/workflow-recipes/src/workflow/pluginWorkloadSdkProvisioner.codexPolicy.test.ts
@@ -1,4 +1,5 @@
import { describe, expect, it, vi } from 'vitest'
+import { computeGrokPolicyHash } from '@clerum/grok-provider-attempt-contract'
import { computeCodexPolicyHash } from '@clerum/llm-provider-attempt-contract'
import type { WorkflowRecipeSpec } from '../types'
import type { CodexRecipeVerdict } from './codexRecipeVerdict'
@@ -15,6 +16,8 @@ const SANDBOX_NS = 'sandbox-recipes'
const IMAGE = 'registry.example/clerum/mcp-host-slim:sha-current'
const RECIPE = 'codex-sdk'
const MODEL = 'gpt-5.3-codex'
+const GROK_RECIPE = 'grok-sdk'
+const GROK_MODEL = 'grok-4.6'
const RUNTIME = {} as unknown as WorkflowRuntimePlan
@@ -34,6 +37,11 @@ const CODEX_SPEC = {
pluginWorkloadSdk: { promptBridge: {} },
} as unknown as WorkflowRecipeSpec
+const GROK_SPEC = {
+ agent: { provider: 'grok-subscription', model: GROK_MODEL },
+ pluginWorkloadSdk: { promptBridge: {} },
+} as unknown as WorkflowRecipeSpec
+
function codexBinding(
overrides: Partial<Omit<PluginWorkloadSdkCodexBindingProof, 'bindingHash'>> = {}
): PluginWorkloadSdkCodexBindingProof {
@@ -50,15 +58,34 @@ function codexBinding(
const MINTED = codexBinding()
/** Build the one verdict the provisioner reads, from a case's intent. */
+function grokBindingProof(
+ overrides: Partial<Omit<PluginWorkloadSdkCodexBindingProof, 'bindingHash'>> = {}
+): PluginWorkloadSdkCodexBindingProof {
+ const fields = {
+ connectionKey: 'team-grok',
+ catalogRevision: 5,
+ credentialRevision: 2,
+ model: GROK_MODEL,
+ ...overrides,
+ }
+ return { ...fields, bindingHash: computeGrokPolicyHash(fields) }
+}
+
+const GROK_MINTED = grokBindingProof()
+
function verdictFor(opts: {
codexBinding?: PluginWorkloadSdkCodexBindingProof | null
codexBindingUndecidable?: boolean
+ grokBinding?: PluginWorkloadSdkCodexBindingProof | null
+ grokBindingUndecidable?: boolean
}): CodexRecipeVerdict {
const undecidable = opts.codexBindingUndecidable === true
+ const grokUndecidable = opts.grokBindingUndecidable === true
const binding = opts.codexBinding ?? null
+ const grokBinding = opts.grokBinding ?? null
return {
- provenance: undecidable ? 'uncertain' : 'authoritative',
- provenanceReason: undecidable ? 'parent_spec_unavailable' : 'standalone',
+ provenance: undecidable || grokUndecidable ? 'uncertain' : 'authoritative',
+ provenanceReason: undecidable || grokUndecidable ? 'parent_spec_unavailable' : 'standalone',
connectionKey: 'team-plus',
projection: {
targets: [],
@@ -77,16 +104,22 @@ function verdictFor(opts: {
grokProjection: {
targets: [],
eligibleTargets: [],
- derivedScopes: [],
+ derivedScopes: grokBinding ? ['llm:grok:execute'] : [],
requiresCodexProxyEgress: false,
- requiresGrokProxyEgress: false,
+ requiresGrokProxyEgress: Boolean(grokBinding) && !grokUndecidable,
catalogContentHash: null,
catalogRevision: null,
connectionRevision: null,
- eligibility: 'ineligible',
- reason: 'static_only',
+ eligibility: grokUndecidable ? 'uncertain' : grokBinding ? 'eligible' : 'ineligible',
+ reason: grokUndecidable ? 'provenance_uncertain' : grokBinding ? 'eligible' : 'static_only',
driftHashInput: '{}',
},
+ grokBinding: grokUndecidable ? null : grokBinding,
+ grokBindingReason: grokUndecidable
+ ? 'provenance_uncertain'
+ : grokBinding
+ ? 'eligible'
+ : 'static_only',
}
}
@@ -132,9 +165,52 @@ function desiredRuntimeContractHash(): string {
)
}
-function makeHarness(configureResult: unknown) {
+function grokRuntimeContractHash(): string {
+ return pluginWorkloadSdkRuntimeContractHash(
+ buildMcpHostPod(
+ GROK_RECIPE,
+ GROK_SPEC.agent,
+ TEST_CONFIG,
+ GROK_RECIPE,
+ SANDBOX_NS,
+ undefined,
+ undefined,
+ undefined,
+ {
+ mountWorkflowOutput: false,
+ pluginWorkloadSdkCapabilities: ['promptBridge'],
+ pluginWorkloadSdkRuntimeMode: 'sdk-only',
+ }
+ )
+ )
+}
+
+function readyGrokBootstrapBody(binding: PluginWorkloadSdkCodexBindingProof | null) {
+ return {
+ status: 202,
+ body: {
+ configured: true,
+ ready: true,
+ provider: 'grok-subscription',
+ model: GROK_MODEL,
+ contractVersion: 3,
+ policyReady: true,
+ policyState: 'active',
+ policyRevision: 7,
+ policyHash: 'b'.repeat(64),
+ defaultTargetRef: 'target/grok',
+ defaultProvider: 'grok-subscription',
+ defaultModel: GROK_MODEL,
+ ...(binding ? { subscriptionBinding: binding } : {}),
+ },
+ }
+}
+
+function makeHarness(configureResult: unknown, spec: WorkflowRecipeSpec = CODEX_SPEC) {
let podUid = 'pod-uid-1'
- const runtimeContractHash = desiredRuntimeContractHash()
+ const recipeName = spec === GROK_SPEC ? GROK_RECIPE : RECIPE
+ const runtimeContractHash =
+ spec === GROK_SPEC ? grokRuntimeContractHash() : desiredRuntimeContractHash()
const readNamespacedPod = vi.fn().mockImplementation(async () => ({
metadata: {
uid: podUid,
@@ -174,13 +250,15 @@ function makeHarness(configureResult: unknown) {
const reconcile = (opts: {
codexBinding?: PluginWorkloadSdkCodexBindingProof | null
codexBindingUndecidable?: boolean
+ grokBinding?: PluginWorkloadSdkCodexBindingProof | null
+ grokBindingUndecidable?: boolean
}) =>
provisioner.ensureEagerSdkMcpHost(
- RECIPE,
+ recipeName,
'recipe-uid',
SANDBOX_NS,
- RECIPE,
- CODEX_SPEC,
+ recipeName,
+ spec,
RUNTIME,
{
mcpHostPhase: 'Running',
@@ -381,3 +459,72 @@ describe('eager Codex policy gate', () => {
expect(harness.provisioner.getBootstrapProof(RECIPE)).toBeUndefined()
})
})
+
+describe('eager Grok policy gate', () => {
+ it('accepts a Grok hash on subscriptionBinding and reports ready', async () => {
+ const harness = makeHarness(readyGrokBootstrapBody(GROK_MINTED), GROK_SPEC)
+ expect(await harness.reconcile({ grokBinding: GROK_MINTED })).toBe('ready')
+ expect(harness.configure).toHaveBeenCalledWith(
+ 'grok-subscription',
+ GROK_MODEL,
+ expect.any(String),
+ 'configure-token',
+ 'promptBridge',
+ GROK_MINTED
+ )
+ expect(harness.provisioner.getBootstrapProof(GROK_RECIPE)).toMatchObject({
+ contractVersion: 3,
+ provider: 'grok-subscription',
+ subscriptionBinding: GROK_MINTED,
+ policyReady: true,
+ })
+ })
+
+ it('skips reconfigure when Grok provenance is uncertain and the same pod still holds the binding', async () => {
+ const harness = makeHarness(readyGrokBootstrapBody(GROK_MINTED), GROK_SPEC)
+ expect(await harness.reconcile({ grokBinding: GROK_MINTED })).toBe('ready')
+ expect(harness.configure).toHaveBeenCalledTimes(1)
+ expect(
+ await harness.reconcile({ grokBinding: GROK_MINTED, grokBindingUndecidable: true })
+ ).toBe('ready')
+ expect(harness.configure).toHaveBeenCalledTimes(1)
+ })
+
+ it('rejects a Grok bootstrap whose hash is a Codex digest', async () => {
+ const forged = {
+ ...GROK_MINTED,
+ bindingHash: computeCodexPolicyHash({
+ model: GROK_MODEL,
+ catalogRevision: 5,
+ credentialRevision: 2,
+ connectionKey: 'team-grok',
+ }),
+ }
+ const harness = makeHarness(readyGrokBootstrapBody(forged), GROK_SPEC)
+ expect(await harness.reconcile({ grokBinding: GROK_MINTED })).toBe('deploying')
+ expect(harness.provisioner.getBootstrapProof(GROK_RECIPE)).toBeUndefined()
+ })
+
+ it('accepts execution_binding_missing as awaiting_policy when Grok has no grant', async () => {
+ const harness = makeHarness(
+ {
+ status: 202,
+ body: {
+ configured: true,
+ ready: true,
+ provider: 'grok-subscription',
+ model: GROK_MODEL,
+ contractVersion: 3,
+ policyState: 'binding_missing',
+ policyReason: 'execution_binding_missing',
+ },
+ },
+ GROK_SPEC
+ )
+ expect(await harness.reconcile({ grokBinding: null })).toBe('awaiting_policy')
+ expect(harness.provisioner.getBootstrapProof(GROK_RECIPE)).toMatchObject({
+ policyReady: false,
+ policyReason: 'execution_binding_missing',
+ })
+ })
+})
diff --git a/workflow-recipes/src/workflow/pluginWorkloadSdkProvisioner.imageDrift.test.ts b/workflow-recipes/src/workflow/pluginWorkloadSdkProvisioner.imageDrift.test.ts
index 2224f6795..2f123606f 100644
--- a/workflow-recipes/src/workflow/pluginWorkloadSdkProvisioner.imageDrift.test.ts
+++ b/workflow-recipes/src/workflow/pluginWorkloadSdkProvisioner.imageDrift.test.ts
@@ -172,6 +172,8 @@ const decidedVerdict: CodexRecipeVerdict = {
reason: 'static_only',
driftHashInput: '{}',
},
+ grokBinding: null,
+ grokBindingReason: 'static_only',
}
describe('ensureEagerSdkMcpHost image-drift roll', () => {
@@ -756,6 +758,8 @@ describe('ensureEagerSdkMcpHost ConfigMap snapshot skip', () => {
reason: 'static_only',
driftHashInput: '{}',
},
+ grokBinding: null,
+ grokBindingReason: 'static_only',
} satisfies CodexRecipeVerdict,
}
)
diff --git a/workflow-recipes/src/workflow/pluginWorkloadSdkProvisioner.ts b/workflow-recipes/src/workflow/pluginWorkloadSdkProvisioner.ts
index 50daa5290..5bdd0b07c 100644
--- a/workflow-recipes/src/workflow/pluginWorkloadSdkProvisioner.ts
+++ b/workflow-recipes/src/workflow/pluginWorkloadSdkProvisioner.ts
@@ -36,6 +36,7 @@ import {
type PluginWorkloadSdkCodexBindingProof,
readVerifiedSdkOnlyCodexBinding,
} from './sdkOnlyCodexBinding'
+import { readVerifiedSdkOnlyGrokBinding } from './sdkOnlyGrokBinding'
import { buildPluginWorkloadSdkTokenSecret } from './secretFactory'
import type { WorkflowConfig } from './types'
@@ -82,6 +83,7 @@ export interface EagerSdkBootstrapProof {
contractVersion: 2 | 3
podUid: string
codexBinding?: PluginWorkloadSdkCodexBindingProof
+ subscriptionBinding?: PluginWorkloadSdkCodexBindingProof
provider?: string
model?: string
policyReady?: boolean
@@ -394,11 +396,13 @@ export class PluginWorkloadSdkProvisioner {
}
if (promptBridge && !mcpHostAgent) return 'failed'
- if (
- opts.codexVerdict.projection.eligibility === 'uncertain' &&
- promptBridge &&
+ const brokerProjectionUncertain =
mcpHostAgent?.provider === 'codex-subscription'
- ) {
+ ? opts.codexVerdict.projection.eligibility === 'uncertain'
+ : mcpHostAgent?.provider === 'grok-subscription'
+ ? opts.codexVerdict.grokProjection.eligibility === 'uncertain'
+ : false
+ if (brokerProjectionUncertain && promptBridge) {
const existing = this.eagerSdkBootstrapProofByRecipe.get(recipeName)
if (existing && existing.podUid !== readiness.uid) {
// Proof of a pod that has since been replaced. The new pod has never
@@ -415,8 +419,9 @@ export class PluginWorkloadSdkProvisioner {
!existing ||
existing.policyReady === false ||
existing.contractVersion !== 3 ||
- !existing.codexBinding ||
- existing.policyReason === 'codex_execution_binding_missing'
+ !(existing.codexBinding || existing.subscriptionBinding) ||
+ existing.policyReason === 'codex_execution_binding_missing' ||
+ existing.policyReason === 'execution_binding_missing'
) {
return 'awaiting_policy'
}
@@ -426,8 +431,11 @@ export class PluginWorkloadSdkProvisioner {
// verdict the caller computed once for this pass. The provisioner never
// re-derives either after its own awaits.
const resolvedCodexBinding = opts.codexVerdict.hostBinding
+ const resolvedGrokBinding = opts.codexVerdict.grokBinding
+ const resolvedBrokerBinding =
+ mcpHostAgent?.provider === 'grok-subscription' ? resolvedGrokBinding : resolvedCodexBinding
const capabilityFamily = promptBridge ? 'promptBridge' : 'clientNotifications'
- const configureKey = `${readiness.uid}:${capabilityFamily}:${mcpHostAgent?.provider ?? 'none'}:${mcpHostAgent?.model ?? 'none'}:${resolvedCodexBinding?.bindingHash ?? 'none'}`
+ const configureKey = `${readiness.uid}:${capabilityFamily}:${mcpHostAgent?.provider ?? 'none'}:${mcpHostAgent?.model ?? 'none'}:${resolvedBrokerBinding?.bindingHash ?? 'none'}`
try {
const wrcConfigureToken = await this.deps.tokenFactory.signWrcConfigureToken(
recipeName,
@@ -442,7 +450,7 @@ export class PluginWorkloadSdkProvisioner {
mcpHostEndpoint,
wrcConfigureToken,
'promptBridge',
- resolvedCodexBinding
+ resolvedBrokerBinding
)
: await modelConfigHandler.configurePluginWorkloadSdkBootstrap(
undefined,
@@ -460,7 +468,8 @@ export class PluginWorkloadSdkProvisioner {
// pending policy reason instead.
if (
promptBridge &&
- mcpHostAgent?.provider === 'codex-subscription' &&
+ (mcpHostAgent?.provider === 'codex-subscription' ||
+ mcpHostAgent?.provider === 'grok-subscription') &&
result.body?.policyReason === 'codex_bootstrap_contract_stale'
) {
log.warn(
@@ -522,6 +531,23 @@ export class PluginWorkloadSdkProvisioner {
},
})
}
+ if (
+ promptBridge &&
+ mcpHostAgent?.provider === 'grok-subscription' &&
+ (proof.subscriptionBinding?.bindingHash ?? null) !==
+ (resolvedGrokBinding?.bindingHash ?? null)
+ ) {
+ this.eagerSdkBootstrapProofByRecipe.delete(recipeName)
+ return this.recordEagerConfigureFailure(recipeName, configureKey, log, {
+ reason:
+ 'Plugin Workload SDK bootstrap echoed a Grok binding that does not match the minted binding',
+ detail: {
+ status: result.status,
+ mintedBindingHash: resolvedGrokBinding?.bindingHash ?? null,
+ echoedBindingHash: proof.subscriptionBinding?.bindingHash ?? null,
+ },
+ })
+ }
this.eagerSdkBootstrapProofByRecipe.set(recipeName, proof)
this.eagerSdkConfigureFailuresByRecipe.delete(recipeName)
if (promptBridge && proof.policyReady === false) {
@@ -536,6 +562,15 @@ export class PluginWorkloadSdkProvisioner {
) {
return 'awaiting_policy'
}
+ if (
+ promptBridge &&
+ mcpHostAgent?.provider === 'grok-subscription' &&
+ (proof.contractVersion !== 3 ||
+ !proof.subscriptionBinding ||
+ proof.policyReason === 'execution_binding_missing')
+ ) {
+ return 'awaiting_policy'
+ }
if (clientNotifications && proof.clientNotificationsPolicyReady === false) {
return 'awaiting_policy'
}
@@ -738,10 +773,17 @@ function parseEagerSdkBootstrapProof(
) {
return null
}
- if (body.provider === 'codex-subscription' && body.contractVersion !== 3) {
+ if (
+ (body.provider === 'codex-subscription' || body.provider === 'grok-subscription') &&
+ body.contractVersion !== 3
+ ) {
return null
}
+ const grok = body.provider === 'grok-subscription'
const codexBinding = parseCodexBindingProof(body.codexBinding, expectedModel)
+ const subscriptionBinding = grok
+ ? parseGrokBindingProof(body.subscriptionBinding ?? body.codexBinding, expectedModel)
+ : parseCodexBindingProof(body.subscriptionBinding, expectedModel)
if (
body.provider === 'codex-subscription' &&
body.policyReason === 'codex_execution_binding_missing'
@@ -758,9 +800,25 @@ function parseEagerSdkBootstrapProof(
verifiedAt: new Date().toISOString(),
}
}
+ if (body.provider === 'grok-subscription' && body.policyReason === 'execution_binding_missing') {
+ return {
+ ready: true,
+ contractVersion: 3,
+ podUid,
+ provider: body.provider,
+ model: body.model,
+ policyReady: false,
+ policyState: typeof body.policyState === 'string' ? body.policyState : 'binding_missing',
+ policyReason: 'execution_binding_missing',
+ verifiedAt: new Date().toISOString(),
+ }
+ }
if (body.provider === 'codex-subscription' && !codexBinding) {
return null
}
+ if (body.provider === 'grok-subscription' && !subscriptionBinding) {
+ return null
+ }
const hasPolicyProof =
Number.isSafeInteger(body.policyRevision) &&
Number(body.policyRevision) >= 1 &&
@@ -779,10 +837,12 @@ function parseEagerSdkBootstrapProof(
provider: body.provider,
model: body.model,
...(codexBinding ? { codexBinding } : {}),
+ ...(subscriptionBinding ? { subscriptionBinding } : {}),
policyReady:
body.policyReady !== false &&
hasPolicyProof &&
- (body.provider !== 'codex-subscription' || Boolean(codexBinding)),
+ (body.provider !== 'codex-subscription' || Boolean(codexBinding)) &&
+ (body.provider !== 'grok-subscription' || Boolean(subscriptionBinding)),
policyState: typeof body.policyState === 'string' ? body.policyState : 'unknown',
...(typeof body.policyReason === 'string' ? { policyReason: body.policyReason } : {}),
verifiedAt: new Date().toISOString(),
@@ -816,3 +876,11 @@ function parseCodexBindingProof(
if (!expectedModel) return undefined
return readVerifiedSdkOnlyCodexBinding(value, expectedModel) ?? undefined
}
+
+function parseGrokBindingProof(
+ value: unknown,
+ expectedModel: string | undefined
+): PluginWorkloadSdkCodexBindingProof | undefined {
+ if (!expectedModel) return undefined
+ return readVerifiedSdkOnlyGrokBinding(value, expectedModel) ?? undefined
+}
diff --git a/workflow-recipes/src/workflow/sdkOnlyGrokBinding.test.ts b/workflow-recipes/src/workflow/sdkOnlyGrokBinding.test.ts
new file mode 100644
index 000000000..1f5ebabc2
--- /dev/null
+++ b/workflow-recipes/src/workflow/sdkOnlyGrokBinding.test.ts
@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest'
+import { computeGrokPolicyHash } from '@clerum/grok-provider-attempt-contract'
+import { computeCodexPolicyHash } from '@clerum/llm-provider-attempt-contract'
+import { mintSdkOnlyGrokBindingProof, readVerifiedSdkOnlyGrokBinding } from './sdkOnlyGrokBinding'
+
+const MODEL = 'grok-4.6'
+
+const HASH = computeGrokPolicyHash({
+ model: MODEL,
+ catalogRevision: 5,
+ credentialRevision: 2,
+ connectionKey: 'team-grok',
+})
+
+describe('readVerifiedSdkOnlyGrokBinding', () => {
+ it('rebuilds a five-field proof and drops extra keys', () => {
+ const proof = {
+ connectionKey: 'team-grok',
+ catalogRevision: 5,
+ credentialRevision: 2,
+ model: MODEL,
+ bindingHash: HASH,
+ extra: true,
+ }
+ expect(readVerifiedSdkOnlyGrokBinding(proof, MODEL)).toEqual({
+ connectionKey: 'team-grok',
+ catalogRevision: 5,
+ credentialRevision: 2,
+ model: MODEL,
+ bindingHash: HASH,
+ })
+ })
+
+ it('rejects a Codex digest for the same five fields', () => {
+ const proof = mintSdkOnlyGrokBindingProof({
+ connectionKey: 'team-grok',
+ catalogRevision: 5,
+ credentialRevision: 2,
+ model: MODEL,
+ })
+ expect(
+ readVerifiedSdkOnlyGrokBinding(
+ {
+ ...proof,
+ bindingHash: computeCodexPolicyHash({
+ model: MODEL,
+ catalogRevision: 5,
+ credentialRevision: 2,
+ connectionKey: 'team-grok',
+ }),
+ },
+ MODEL
+ )
+ ).toBeNull()
+ expect(readVerifiedSdkOnlyGrokBinding(proof, MODEL)).toEqual(proof)
+ })
+
+ it('rejects the unassigned sentinel', () => {
+ expect(
+ readVerifiedSdkOnlyGrokBinding(
+ {
+ connectionKey: 'unassigned',
+ catalogRevision: 5,
+ credentialRevision: 2,
+ model: MODEL,
+ bindingHash: HASH,
+ },
+ MODEL
+ )
+ ).toBeNull()
+ })
+})
diff --git a/workflow-recipes/src/workflow/sdkOnlyGrokBinding.ts b/workflow-recipes/src/workflow/sdkOnlyGrokBinding.ts
new file mode 100644
index 000000000..0099d2c90
--- /dev/null
+++ b/workflow-recipes/src/workflow/sdkOnlyGrokBinding.ts
@@ -0,0 +1,51 @@
+import { computeGrokPolicyHash } from '@clerum/grok-provider-attempt-contract'
+import type { PluginWorkloadSdkCodexBindingProof } from './sdkOnlyCodexBinding'
+import { isPluginWorkloadSdkCodexBindingProof } from './sdkOnlyCodexBinding'
+
+export function mintSdkOnlyGrokBindingProof(binding: {
+ connectionKey: string
+ catalogRevision: number
+ credentialRevision: number
+ model: string
+}): PluginWorkloadSdkCodexBindingProof {
+ return {
+ connectionKey: binding.connectionKey,
+ catalogRevision: binding.catalogRevision,
+ credentialRevision: binding.credentialRevision,
+ model: binding.model,
+ bindingHash: computeGrokPolicyHash({
+ model: binding.model,
+ catalogRevision: binding.catalogRevision,
+ credentialRevision: binding.credentialRevision,
+ connectionKey: binding.connectionKey,
+ }),
+ }
+}
+
+export function verifySdkOnlyGrokBindingHash(binding: PluginWorkloadSdkCodexBindingProof): boolean {
+ return (
+ binding.bindingHash ===
+ computeGrokPolicyHash({
+ model: binding.model,
+ catalogRevision: binding.catalogRevision,
+ credentialRevision: binding.credentialRevision,
+ connectionKey: binding.connectionKey,
+ })
+ )
+}
+
+export function readVerifiedSdkOnlyGrokBinding(
+ value: unknown,
+ model: string
+): PluginWorkloadSdkCodexBindingProof | null {
+ if (!isPluginWorkloadSdkCodexBindingProof(value)) return null
+ if (value.model !== model) return null
+ if (!verifySdkOnlyGrokBindingHash(value)) return null
+ return {
+ connectionKey: value.connectionKey,
+ catalogRevision: value.catalogRevision,
+ credentialRevision: value.credentialRevision,
+ model: value.model,
+ bindingHash: value.bindingHash,
+ }
+}
diff --git a/workflow-recipes/tests/unit/workflow/modelConfigHandler.pluginSdkBroker.test.ts b/workflow-recipes/tests/unit/workflow/modelConfigHandler.pluginSdkBroker.test.ts
index 208c0b4ad..7bdd678f6 100644
--- a/workflow-recipes/tests/unit/workflow/modelConfigHandler.pluginSdkBroker.test.ts
+++ b/workflow-recipes/tests/unit/workflow/modelConfigHandler.pluginSdkBroker.test.ts
@@ -1,4 +1,5 @@
import { describe, expect, it, vi } from 'vitest'
+import { computeGrokPolicyHash } from '@clerum/grok-provider-attempt-contract'
import { computeCodexPolicyHash } from '@clerum/llm-provider-attempt-contract'
import {
type K8sSecretReader,
@@ -266,6 +267,67 @@ describe('ModelConfigHandler Plugin SDK per-attempt credential broker', () => {
expect(k8s.readSecret).not.toHaveBeenCalled()
})
+ it('publishes Grok SDK bootstrap as v3 with subscriptionBinding only', async () => {
+ const binding = {
+ connectionKey: 'team-grok',
+ catalogRevision: 5,
+ credentialRevision: 2,
+ model: 'grok-4.6',
+ bindingHash: computeGrokPolicyHash({
+ model: 'grok-4.6',
+ catalogRevision: 5,
+ credentialRevision: 2,
+ connectionKey: 'team-grok',
+ }),
+ }
+ const mcpHost: McpHostClient = {
+ configure: vi.fn(async () => ({ status: 500, body: {} })),
+ configurePluginWorkloadSdkBootstrap: vi.fn(async () => ({
+ status: 200,
+ body: {
+ configured: true,
+ ready: true,
+ provider: 'grok-subscription',
+ model: 'grok-4.6',
+ contractVersion: 3,
+ policyReady: true,
+ policyState: 'active',
+ subscriptionBinding: { ...binding, leaked: 'drop-me' },
+ },
+ })),
+ }
+ const k8s = reader()
+ const handler = new ModelConfigHandler(k8s, mcpHost)
+ const result = await handler.configurePluginWorkloadSdkBootstrap(
+ 'grok-subscription',
+ 'grok-4.6',
+ 'http://mcp-host:8090',
+ 'wrc-token',
+ 'promptBridge',
+ binding
+ )
+
+ expect(result.status).toBe(202)
+ expect(result.body).toMatchObject({
+ contractVersion: 3,
+ provider: 'grok-subscription',
+ model: 'grok-4.6',
+ subscriptionBinding: binding,
+ })
+ expect(result.body).not.toHaveProperty('codexBinding')
+ expect(result.body.subscriptionBinding).not.toHaveProperty('leaked')
+ expect(mcpHost.configurePluginWorkloadSdkBootstrap).toHaveBeenCalledWith(
+ 'http://mcp-host:8090',
+ 'wrc-token',
+ {
+ provider: 'grok-subscription',
+ model: 'grok-4.6',
+ contractVersion: 3,
+ subscriptionBinding: binding,
+ }
+ )
+ })
+
it('drops an echoed Codex binding whose hash does not verify', async () => {
// Shape validation alone would republish this binding to WRC. The hash is
// the only thing tying the five fields to the policy WRC minted, so an