Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import { PROVIDER_AUTH_MODE, isLlmProviderId } from '@clerum/llm-providers'
import { CircuitBreaker } from '../domain/circuitBreaker'
import {
PluginWorkloadError,
isKnownPluginWorkloadErrorCode,
isKnownPluginWorkloadErrorReason,
} from '../domain/errors'
import type { PromptBridgeTarget } from '../domain/types'
import { readSdkOnlyCodexBinding } from '../sdkOnlyCodexBinding'
import { readSdkOnlyGrokBinding } from '../sdkOnlyGrokBinding'
/**
* Anti-corruption layer (plan §3.4): encapsulates the HTTP call to
* control-api's /mcp-host/plugin-workload-sdk/* gateway routes and maps
* status codes + error bodies into PluginWorkloadError. Internal control-api
* response details never reach the workload.
*
* Resilience: 3 retries with exponential backoff on transient failures
* (5xx, network), plus a 50%-over-30s circuit breaker that short-circuits
* to provider_unavailable while open (resets after 60s without calls).
*/
function isOauthBrokerProvider(provider: string): boolean {
return isLlmProviderId(provider) && PROVIDER_AUTH_MODE[provider] === 'oauth-broker'
}
export interface ControlApiClientOptions {
baseUrl: string
getAccessToken: () => string
/**
* Refresh-on-401 hook (plan §12). The mcp-host runtime access token (TTL
* ~600s) is read live via getAccessToken(); when control-api rejects it with
* 401 the token has aged out. This rotates the shared runtime auth so the
* retry — and every later call — reads a fresh token. Without it an always-on
* SDK mcp-host that makes no other gateway calls (no approvals, no usage)
* would 401 forever once its boot token expires, killing promptBridge and
* clientNotifications after ~10 minutes. Mirrors UsageReporter and the
* approval clients, which already refresh-on-401 on the same shared auth.
*/
refreshOnUnauthorized?: () => Promise<void>
fetchImpl?: typeof fetch
maxRetries?: number
retryBaseDelayMs?: number
breaker?: CircuitBreaker
}
export interface AuthorizePromptBridgeResponse {
contractVersion: 2
invocationId: string
replay: boolean
providerCallRequired: boolean
status: string
model: string
modelPolicy: { provider: string; model: string; temperature?: number; maxCostUsd?: number } | null
selectedTarget: PromptBridgeTarget
authorizedTargets: PromptBridgeTarget[]
attemptGeneration: number
policyRevision: number
policyHash: string
/**
* Per-grant output ceiling, or null when the grant sets none. Enforced as
* `max_tokens` on API-key providers; codex-subscription cannot bind it on
* the ChatGPT wire, where the contract's LIMITS.maxOutputTokens is the only
* bound.
*/
maxOutputTokens: number | null
}
export interface PluginWorkloadSdkCapabilities {
contractVersion: 2 | 3
supportedContractVersions: number[]
targetAwarePromptBridge: true
attemptLedger: true
credentialTickets: true
policyState: string
policyRevision: number
policyHash: string | null
defaultTargetRef: string | null
defaultProvider: string | null
defaultModel: string | null
defaultConnectionRef: string | null
v2Ready: boolean
/** Present only when the grant default is oauth-broker (reservation-only Codex). */
reservationOnlyOauthBroker?: true
/**
* Present only when this control-api can publish the authoritative Codex
* catalog/credential revisions. Absent means the peer predates them, not
* that the binding is stale — see `codexBindingReady`.
*/
codexBindingRevisions?: true
defaultCatalogRevision?: number
defaultCredentialRevision?: number
clientNotificationsPolicyState: string
clientNotificationsReady: boolean
}
export interface PluginWorkloadSdkBootstrapProof {
ready: true
contractVersion: 2 | 3
provider: string
model: string
policyReady: boolean
policyState: string
policyReason?:
| 'grant_missing'
| 'policy_unreviewed'
| 'policy_revoking'
| 'policy_disabled'
| '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
* operator creates its promptBridge grant. The grant is still required for
* every request and is checked by the authorization endpoint against this
* binding.
*/
policyRevision?: number
policyHash?: string
defaultTargetRef?: string
defaultProvider?: string
defaultModel?: string
clientNotificationsPolicyReady?: boolean
clientNotificationsPolicyState?: string
clientNotificationsPolicyReason?: string
}
export interface PluginWorkloadSdkClientNotificationsBootstrapProof {
ready: true
contractVersion: 2
policyReady: boolean
policyState: string
policyReason?:
| 'grant_missing'
| 'policy_unreviewed'
| 'policy_revoking'
| 'policy_disabled'
| 'policy_not_ready'
}
export interface ReissuedPromptBridgeCredentialTicket {
invocationId: string
attemptGeneration: number
providerAttemptId: string
providerAttemptIndex: number
targetRef: string
credentialTicket: string
reservationOnly?: true
policyRevision: number
policyHash: string
expiresInSeconds: number
}
export interface FinalizePromptBridgeResponse {
invocationId: string
providerAttemptId: string
status: 'complete' | 'failed' | 'provider_unavailable'
outcome: 'exact' | 'unknown' | 'not_executed'
idempotent: boolean
usageAccepted: boolean
}
export interface SubmitClientNotificationResponse {
notificationId: string
replay: boolean
status: string
eventType: string
target: { targetRef?: string; userRef?: string }
}
export interface ClientNotificationRecipient {
userRef: string
displayName: string
}
export interface ListClientNotificationRecipientsResponse {
recipients: ClientNotificationRecipient[]
}
const sleep = (ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms))
function isAuthorizePromptBridgeResponse(v: unknown): v is AuthorizePromptBridgeResponse {
if (typeof v !== 'object' || v === null) return false
const r = v as Record<string, unknown>
return (
r.contractVersion === 2 &&
typeof r.invocationId === 'string' &&
typeof r.replay === 'boolean' &&
typeof r.providerCallRequired === 'boolean' &&
typeof r.status === 'string' &&
typeof r.model === 'string' &&
(r.modelPolicy === null ||
(typeof r.modelPolicy === 'object' &&
r.modelPolicy !== null &&
typeof (r.modelPolicy as Record<string, unknown>).provider === 'string' &&
typeof (r.modelPolicy as Record<string, unknown>).model === 'string')) &&
isPromptBridgeTarget(r.selectedTarget) &&
Array.isArray(r.authorizedTargets) &&
r.authorizedTargets.length > 0 &&
r.authorizedTargets.every(isPromptBridgeTarget) &&
Number.isInteger(r.attemptGeneration) &&
(r.attemptGeneration as number) >= 1 &&
Number.isInteger(r.policyRevision) &&
(r.policyRevision as number) >= 1 &&
typeof r.policyHash === 'string' &&
/^[a-f0-9]{64}$/.test(r.policyHash) &&
// A grant cap of 0 is not "no cap" — it would clamp every response
// to nothing. Reject it here rather than let Math.min silently zero the
// request.
(r.maxOutputTokens === null ||
(Number.isInteger(r.maxOutputTokens) && Number(r.maxOutputTokens) >= 1))
)
}
function isPluginWorkloadSdkCapabilities(v: unknown): v is PluginWorkloadSdkCapabilities {
if (typeof v !== 'object' || v === null) return false
const value = v as Record<string, unknown>
return (
(value.contractVersion === 2 || value.contractVersion === 3) &&
Array.isArray(value.supportedContractVersions) &&
value.supportedContractVersions.includes(2) &&
value.targetAwarePromptBridge === true &&
value.attemptLedger === true &&
value.credentialTickets === true &&
typeof value.policyState === 'string' &&
Number.isInteger(value.policyRevision) &&
Number(value.policyRevision) >= 0 &&
(value.policyHash === null || typeof value.policyHash === 'string') &&
(value.defaultTargetRef === null || typeof value.defaultTargetRef === 'string') &&
(value.defaultProvider === null || typeof value.defaultProvider === 'string') &&
(value.defaultModel === null || typeof value.defaultModel === 'string') &&
(value.defaultConnectionRef === undefined ||
value.defaultConnectionRef === null ||
typeof value.defaultConnectionRef === 'string') &&
typeof value.v2Ready === 'boolean' &&
(value.reservationOnlyOauthBroker === undefined || value.reservationOnlyOauthBroker === true) &&
(value.codexBindingRevisions === undefined || value.codexBindingRevisions === true) &&
// Bounds mirror the codex_subscription_connections CHECKs —
// `catalog_revision BIGINT NOT NULL DEFAULT 0 CHECK (>= 0)` and
// `credential_revision BIGINT NOT NULL DEFAULT 1 CHECK (>= 1)`. These were
// inverted, so a connection whose catalog was never synced (revision 0,
// the DEFAULT) failed the whole capabilities contract with
// protocol_mismatch instead of resolving to codexBindingReady: false.
(value.defaultCatalogRevision === undefined ||
(Number.isInteger(value.defaultCatalogRevision) &&
Number(value.defaultCatalogRevision) >= 0)) &&
(value.defaultCredentialRevision === undefined ||
(Number.isInteger(value.defaultCredentialRevision) &&
Number(value.defaultCredentialRevision) >= 1)) &&
typeof value.clientNotificationsPolicyState === 'string' &&
typeof value.clientNotificationsReady === 'boolean'
)
}
function isReissuedPromptBridgeCredentialTicket(
value: unknown
): value is ReissuedPromptBridgeCredentialTicket {
if (typeof value !== 'object' || value === null) return false
const ticket = value as Record<string, unknown>
return (
typeof ticket.invocationId === 'string' &&
Number.isInteger(ticket.attemptGeneration) &&
(ticket.attemptGeneration as number) >= 1 &&
typeof ticket.providerAttemptId === 'string' &&
ticket.providerAttemptId.length > 0 &&
Number.isInteger(ticket.providerAttemptIndex) &&
(ticket.providerAttemptIndex as number) >= 1 &&
typeof ticket.targetRef === 'string' &&
typeof ticket.credentialTicket === 'string' &&
(ticket.credentialTicket.length > 0 || ticket.reservationOnly === true) &&
Number.isInteger(ticket.policyRevision) &&
(ticket.policyRevision as number) >= 1 &&
typeof ticket.policyHash === 'string' &&
/^[a-f0-9]{64}$/.test(ticket.policyHash) &&
Number.isInteger(ticket.expiresInSeconds) &&
(ticket.expiresInSeconds as number) > 0
)
}
function isFinalizePromptBridgeResponse(value: unknown): value is FinalizePromptBridgeResponse {
if (typeof value !== 'object' || value === null) return false
const result = value as Record<string, unknown>
return (
typeof result.invocationId === 'string' &&
typeof result.providerAttemptId === 'string' &&
(result.status === 'complete' ||
result.status === 'failed' ||
result.status === 'provider_unavailable') &&
(result.outcome === 'exact' ||
result.outcome === 'unknown' ||
result.outcome === 'not_executed') &&
typeof result.idempotent === 'boolean' &&
typeof result.usageAccepted === 'boolean'
)
}
function isPromptBridgeTarget(value: unknown): value is PromptBridgeTarget {
if (typeof value !== 'object' || value === null) return false
const target = value as Record<string, unknown>
return (
typeof target.targetRef === 'string' &&
typeof target.provider === 'string' &&
typeof target.model === 'string' &&
typeof target.credentialSlot === 'string' &&
// Optional Codex subscription grant identity (oauth-broker targets only).
(target.connectionRef === undefined || typeof target.connectionRef === 'string')
)
}
function isSubmitClientNotificationResponse(v: unknown): v is SubmitClientNotificationResponse {
if (typeof v !== 'object' || v === null) return false
const r = v as Record<string, unknown>
return (
typeof r.notificationId === 'string' &&
typeof r.replay === 'boolean' &&
typeof r.status === 'string' &&
typeof r.eventType === 'string' &&
typeof r.target === 'object' &&
r.target !== null
)
}
function isListClientNotificationRecipientsResponse(
v: unknown
): v is ListClientNotificationRecipientsResponse {
if (typeof v !== 'object' || v === null) return false
const r = v as Record<string, unknown>
return (
Array.isArray(r.recipients) &&
r.recipients.every(
item =>
typeof item === 'object' &&
item !== null &&
typeof (item as Record<string, unknown>).userRef === 'string' &&
typeof (item as Record<string, unknown>).displayName === 'string'
)
)
}
export class PluginWorkloadSdkControlApiClient {
private readonly breaker: CircuitBreaker
private refreshInFlight: Promise<void> | null = null
private capabilitiesInFlight: Promise<PluginWorkloadSdkCapabilities> | null = null
constructor(private readonly opts: ControlApiClientOptions) {
this.breaker = opts.breaker ?? new CircuitBreaker()
}
/**
* Refresh-and-retry wrapper around postOnce(). On the first `unauthorized`
* (401) from control-api the runtime access token has aged out: rotate the
* shared runtime auth once and retry with the fresh token. A second 401 (or
* no refresh hook) propagates the error so a genuinely bad credential still
* surfaces instead of looping.
*/
private async post(path: string, body: unknown, signal?: AbortSignal): Promise<unknown> {
try {
return await this.postOnce(path, body, signal)
} catch (err) {
if (
err instanceof PluginWorkloadError &&
err.code === 'unauthorized' &&
this.opts.refreshOnUnauthorized
) {
await this.triggerRefresh()
return this.postOnce(path, body, signal)
}
throw err
}
}
/**
* Coalesce concurrent refreshes onto a single attempt — control-api revokes
* refresh JTIs on first use, so parallel promptBridge/clientNotifications
* calls that 401 together must share one rotation rather than burn the chain.
*/
private async triggerRefresh(): Promise<void> {
if (!this.opts.refreshOnUnauthorized) return
if (this.refreshInFlight) {
await this.refreshInFlight
return
}
this.refreshInFlight = this.opts
.refreshOnUnauthorized()
.then(() => undefined)
.catch(err => {
console.warn(
`[PluginWorkloadSdk] refresh-on-401 failed: ${
err instanceof Error ? err.message : String(err)
}`
)
})
try {
await this.refreshInFlight
} finally {
this.refreshInFlight = null
}
}
private async postOnce(path: string, body: unknown, signal?: AbortSignal): Promise<unknown> {
if (!this.breaker.allow()) {
throw new PluginWorkloadError(
'provider_unavailable',
'control-api gateway circuit breaker is open',
true
)
}
const fetchImpl = this.opts.fetchImpl ?? fetch
const url = `${this.opts.baseUrl.replace(/\/+$/, '')}${path}`
const maxRetries = this.opts.maxRetries ?? 3
const baseDelay = this.opts.retryBaseDelayMs ?? 250
let lastError: unknown = null
for (let attempt = 0; attempt <= maxRetries; attempt++) {
// An aborted caller deadline is not a transient network failure: without
// this the `catch` below would swallow every AbortError as retryable and
// burn the remaining attempts after the operation was already over.
if (signal?.aborted) break
if (attempt > 0) await sleep(baseDelay * 2 ** (attempt - 1))
let response: Response
try {
response = await fetchImpl(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${this.opts.getAccessToken()}`,
},
body: JSON.stringify(body),
// The per-request timeout still bounds one hop; a caller-supplied
// signal additionally bounds the whole operation across retries, so
// a finalize deadline cannot be outlived by this loop.
signal: signal
? AbortSignal.any([AbortSignal.timeout(15_000), signal])
: AbortSignal.timeout(15_000),
})
} catch (err) {
// Network failure — retryable.
lastError = err
this.breaker.record(false)
continue
}
if (response.status >= 500) {
lastError = new PluginWorkloadError(
'provider_unavailable',
`control-api responded ${response.status}`,
true
)
this.breaker.record(false)
continue
}
this.breaker.record(true)
if (response.ok) {
return response.json()
}
if (response.status === 404 && path.endsWith('/prompt-bridge/v2')) {
throw new PluginWorkloadError(
'protocol_mismatch',
'control-api does not expose the promptBridge v2 contract; rollout must upgrade control-api before mcp-host',
true
)
}
// Non-retryable 4xx: map the structured code without leaking the body.
const errorBody = (await response.json().catch(() => ({}))) as {
error?: unknown
message?: unknown
retryable?: unknown
reason?: unknown
}
const code = typeof errorBody.error === 'string' ? errorBody.error : ''
if (isKnownPluginWorkloadErrorCode(code)) {
throw new PluginWorkloadError(
code,
typeof errorBody.message === 'string' ? errorBody.message : `request denied (${code})`,
errorBody.retryable === true,
typeof errorBody.reason === 'string' && isKnownPluginWorkloadErrorReason(errorBody.reason)
? errorBody.reason
: undefined
)
}
if (response.status === 401) {
throw new PluginWorkloadError('unauthorized', 'gateway rejected mcp-host credentials')
}
throw new PluginWorkloadError('invalid_request', `request rejected (${response.status})`)
}
throw lastError instanceof Error
? lastError
: new PluginWorkloadError(
'provider_unavailable',
'control-api gateway is unavailable after retries',
true
)
}
private async getOnce(path: string): Promise<unknown> {
if (!this.breaker.allow()) {
throw new PluginWorkloadError(
'provider_unavailable',
'control-api gateway circuit breaker is open',
true
)
}
const fetchImpl = this.opts.fetchImpl ?? fetch
let response: Response
try {
response = await fetchImpl(`${this.opts.baseUrl.replace(/\/+$/, '')}${path}`, {
method: 'GET',
headers: { Authorization: `Bearer ${this.opts.getAccessToken()}` },
})
} catch {
this.breaker.record(false)
throw new PluginWorkloadError(
'provider_unavailable',
'control-api capability probe failed',
true
)
}
if (response.status === 404 || response.status === 405) {
this.breaker.record(true)
throw new PluginWorkloadError(
'protocol_mismatch',
'control-api does not advertise the promptBridge v2 contract; upgrade control-api before mcp-host',
true
)
}
if (response.status >= 500) {
this.breaker.record(false)
throw new PluginWorkloadError(
'provider_unavailable',
`control-api capability probe responded ${response.status}`,
true
)
}
this.breaker.record(true)
if (response.ok) return response.json()
if (response.status === 401) {
throw new PluginWorkloadError('unauthorized', 'gateway rejected mcp-host credentials')
}
throw new PluginWorkloadError(
'protocol_mismatch',
'control-api capability contract was rejected',
true
)
}
private async get(path: string): Promise<unknown> {
try {
return await this.getOnce(path)
} catch (err) {
if (
err instanceof PluginWorkloadError &&
err.code === 'unauthorized' &&
this.opts.refreshOnUnauthorized
) {
await this.triggerRefresh()
return this.getOnce(path)
}
throw err
}
}
/** Fetch the capabilities contract, coalescing only concurrent probes. */
async getPromptBridgeCapabilities(): Promise<PluginWorkloadSdkCapabilities> {
if (this.capabilitiesInFlight) return this.capabilitiesInFlight
const request = this.get('/api/v1/mcp-host/plugin-workload-sdk/capabilities')
.then(result => {
if (!isPluginWorkloadSdkCapabilities(result)) {
throw new PluginWorkloadError(
'protocol_mismatch',
'control-api capability response is not the promptBridge v2 contract',
true
)
}
return {
...result,
defaultConnectionRef: result.defaultConnectionRef ?? null,
}
})
.finally(() => {
if (this.capabilitiesInFlight === request) this.capabilitiesInFlight = null
})
this.capabilitiesInFlight = request
return request
}
/**
* Negotiates the target-aware/JIT wire contract before a prompt. There is no
* legacy fallback: an SDK host must not send multiprovider traffic to an API that
* cannot fence attempts or tickets.
*/
async ensurePromptBridgeCapabilities(): Promise<void> {
const capabilities = await this.getPromptBridgeCapabilities()
if (!capabilities.v2Ready) {
throw new PluginWorkloadError(
'provider_policy_denied',
'control-api promptBridge policy is not ready; an active operator grant is required',
false
)
}
}
/**
* Fresh two-phase bootstrap proof. The completed response is never cached;
* only an in-flight request may be shared. This always proves that
* control-api and mcp-host speak the v2 SDK contract. `policyReady` is a
* separate live signal: a missing or unreviewed grant is a legitimate
* awaiting-policy state, not a provider outage. Policy/default/target
* coherence is enforced again when the workload authorizes its first prompt.
*/
async verifyPromptBridgeBootstrapV2(
expectedProvider: string,
expectedModel: string
): Promise<PluginWorkloadSdkBootstrapProof> {
const capabilities = await this.getPromptBridgeCapabilities()
if (
(capabilities.contractVersion !== 2 && capabilities.contractVersion !== 3) ||
!capabilities.supportedContractVersions.includes(2) ||
capabilities.targetAwarePromptBridge !== true ||
capabilities.attemptLedger !== true ||
capabilities.credentialTickets !== true ||
typeof expectedProvider !== 'string' ||
expectedProvider.length === 0 ||
typeof expectedModel !== 'string' ||
expectedModel.length === 0
) {
throw new PluginWorkloadError(
'protocol_mismatch',
'control-api promptBridge identity bootstrap contract is not ready',
true
)
}
const grok = expectedProvider === 'grok-subscription'
const binding = grok
? readSdkOnlyGrokBinding()
: isOauthBrokerProvider(expectedProvider)
? readSdkOnlyCodexBinding()
: null
const reservationOnlyReady = capabilities.reservationOnlyOauthBroker === true
const contractReady =
capabilities.contractVersion === 3 && capabilities.supportedContractVersions.includes(3)
// #533 acceptance criterion 2: the binding must be tied to the catalog and
// credential revisions too, not only to the connection and model. Those
// revisions are authoritative on control-api's connection row, so this can
// only be compared when the peer publishes them. `codexBindingRevisions`
// is that discriminator, and it must be read as "can this API send them",
// never as "is this binding fresh": an older control-api omits the flag,
// and demanding a field it cannot emit would fail closed across a
// mixed-binary window (the #540 shape). When the flag IS present, both
// values are required and must match — a missing or divergent revision is
// a stale binding, and it fails closed here at reconcile rather than at
// the first prompt.
const revisionsPublished = capabilities.codexBindingRevisions === true
const codexRevisionsReady =
!revisionsPublished ||
(binding !== null &&
capabilities.defaultCatalogRevision === binding.catalogRevision &&
capabilities.defaultCredentialRevision === binding.credentialRevision)
const brokerBindingReady =
!isOauthBrokerProvider(expectedProvider) ||
(reservationOnlyReady &&
contractReady &&
binding !== null &&
capabilities.defaultProvider === expectedProvider &&
capabilities.defaultModel === expectedModel &&
binding.model === expectedModel &&
typeof capabilities.defaultConnectionRef === 'string' &&
capabilities.defaultConnectionRef === binding.connectionKey &&
codexRevisionsReady)
const policyReady =
capabilities.v2Ready &&
capabilities.policyRevision >= 1 &&
!!capabilities.policyHash &&
/^[a-f0-9]{64}$/.test(capabilities.policyHash) &&
!!capabilities.defaultTargetRef &&
capabilities.defaultProvider === expectedProvider &&
capabilities.defaultModel === expectedModel &&
brokerBindingReady
const policyReason = policyReady
? undefined
: capabilities.policyState === 'missing'
? 'grant_missing'
: capabilities.policyState === 'legacy_unreviewed'
? 'policy_unreviewed'
: capabilities.policyState === 'revoking'
? 'policy_revoking'
: capabilities.policyState === 'disabled'
? 'policy_disabled'
: isOauthBrokerProvider(expectedProvider) && !brokerBindingReady
? grok
? 'execution_binding_missing'
: 'codex_execution_binding_missing'
: capabilities.v2Ready
? 'bootstrap_target_mismatch'
: 'policy_not_ready'
return {
ready: true,
contractVersion: isOauthBrokerProvider(expectedProvider) ? 3 : 2,
provider: expectedProvider,
model: expectedModel,
policyReady,
policyState: capabilities.policyState,
...(grok ? { bindingReady: brokerBindingReady } : {}),
...(isOauthBrokerProvider(expectedProvider) && !grok
? { codexBindingReady: brokerBindingReady }
: {}),
...(policyReason ? { policyReason } : {}),
...(capabilities.v2Ready &&
capabilities.policyRevision >= 1 &&
capabilities.policyHash &&
/^[a-f0-9]{64}$/.test(capabilities.policyHash) &&
capabilities.defaultTargetRef &&
capabilities.defaultProvider &&
capabilities.defaultModel
? {
policyRevision: capabilities.policyRevision,
policyHash: capabilities.policyHash,
defaultTargetRef: capabilities.defaultTargetRef,
defaultProvider: capabilities.defaultProvider,
defaultModel: capabilities.defaultModel,
}
: {}),
clientNotificationsPolicyReady: capabilities.clientNotificationsReady,
clientNotificationsPolicyState: capabilities.clientNotificationsPolicyState,
...(capabilities.clientNotificationsReady
? {}
: {
clientNotificationsPolicyReason:
capabilities.clientNotificationsPolicyState === 'missing'
? 'grant_missing'
: capabilities.clientNotificationsPolicyState === 'legacy_unreviewed'
? 'policy_unreviewed'
: capabilities.clientNotificationsPolicyState === 'revoking'
? 'policy_revoking'
: capabilities.clientNotificationsPolicyState === 'disabled'
? 'policy_disabled'
: 'policy_not_ready',
}),
}
}
/**
* Fresh readiness proof for the provider-free clientNotifications family.
* It shares the v2 capabilities contract but never invents a provider/model
* binding for a notifications-only recipe.
*/
async verifyClientNotificationsBootstrap(): Promise<PluginWorkloadSdkClientNotificationsBootstrapProof> {
const capabilities = await this.getPromptBridgeCapabilities()
const policyReady = capabilities.clientNotificationsReady
const policyReason = policyReady
? undefined
: capabilities.clientNotificationsPolicyState === 'missing'
? 'grant_missing'
: capabilities.clientNotificationsPolicyState === 'legacy_unreviewed'
? 'policy_unreviewed'
: capabilities.clientNotificationsPolicyState === 'revoking'
? 'policy_revoking'
: capabilities.clientNotificationsPolicyState === 'disabled'
? 'policy_disabled'
: 'policy_not_ready'
return {
ready: true,
contractVersion: 2,
policyReady,
policyState: capabilities.clientNotificationsPolicyState,
...(policyReason ? { policyReason } : {}),
}
}
async authorizePromptBridge(body: {
recipeNamespace: string
recipeName: string
callerRef: string
bootstrapProvider?: string
bootstrapModel?: string
model?: string
provider?: string
targetRef?: string
modelPolicyRef?: string
purpose: string
idempotencyKey: string
messages: Array<{ role: string; content: string }>
metadata?: Record<string, unknown>
correlationId?: string
}): Promise<AuthorizePromptBridgeResponse> {
const result = await this.post('/api/v1/mcp-host/plugin-workload-sdk/prompt-bridge/v2', {
contractVersion: 2,
...body,
})
if (!isAuthorizePromptBridgeResponse(result)) {
throw new PluginWorkloadError(
'provider_unavailable',
'control-api returned an unexpected response shape for authorize-prompt-bridge',
true
)
}
return result
}
/**
* Obtain a one-shot credential ticket immediately before a single target's
* credential resolution. The caller binds the original authorization
* snapshot; the gateway independently derives the credential identity.
*/
async reissuePromptBridgeCredentialTicket(body: {
recipeNamespace: string
recipeName: string
invocationId: string
attemptGeneration: number
target: PromptBridgeTarget
policyRevision: number
policyHash: string
}): Promise<ReissuedPromptBridgeCredentialTicket> {
const result = await this.post(
'/api/v1/mcp-host/plugin-workload-sdk/prompt-bridge/credential-ticket',
{
recipeNamespace: body.recipeNamespace,
recipeName: body.recipeName,
invocationId: body.invocationId,
targetRef: body.target.targetRef,
attemptGeneration: body.attemptGeneration,
}
)
if (!isReissuedPromptBridgeCredentialTicket(result)) {
throw new PluginWorkloadError(
'provider_unavailable',
'control-api returned an unexpected response shape for credential-ticket reissue',
true
)
}
if (
result.invocationId !== body.invocationId ||
result.attemptGeneration !== body.attemptGeneration ||
result.providerAttemptId.length === 0 ||
result.providerAttemptIndex < 1 ||
result.targetRef !== body.target.targetRef ||
result.policyRevision !== body.policyRevision ||
result.policyHash !== body.policyHash
) {
throw new PluginWorkloadError(
'provider_unavailable',
'control-api returned a credential ticket for a different authorization',
false
)
}
return result
}
async reportProviderAttemptStatus(body: {
invocationId: string
recipeNamespace: string
recipeName: string
attemptGeneration: number
providerAttemptId: string
providerAttemptIndex: number
status: 'complete' | 'failed' | 'provider_unavailable' | 'skipped'
}): Promise<void> {
await this.post(
`/api/v1/mcp-host/plugin-workload-sdk/provider-attempts/${encodeURIComponent(
body.providerAttemptId
)}/status`,
body
)
}
async reportInvocationStatus(
invocationId: string,
recipeNamespace: string,
recipeName: string,
status: 'complete' | 'failed' | 'provider_unavailable',
attemptGeneration: number
): Promise<void> {
// The handler owns the conservative policy for a lost ACK: it preserves a
// real provider result, reports provider_unavailable when the physical
// receipt is unknown, and lets the idempotent caller retry this operation.
await this.post(
`/api/v1/mcp-host/plugin-workload-sdk/invocations/${encodeURIComponent(invocationId)}/status`,
{ recipeNamespace, recipeName, status, attemptGeneration }
)
}
/**
* Atomically closes one SDK-only provider attempt and records exact or
* unknown spend. This replaces separate status + usage calls for the
* stepless runtime; the route is idempotent on providerAttemptId.
*/
async finalizePromptBridge(
body: {
recipeNamespace: string
recipeName: string
invocationId: string
attemptGeneration: number
providerAttemptId: string
providerAttemptIndex: number
status: 'complete' | 'failed' | 'provider_unavailable'
reason: string
target: PromptBridgeTarget
usage?: {
llmSecretName: string
callerRef: string
fallbackUsed: boolean
attemptCount: number
inputTokens: number
outputTokens: number
}
},
options?: { signal?: AbortSignal }
): Promise<FinalizePromptBridgeResponse> {
const result = await this.post(
`/api/v1/mcp-host/plugin-workload-sdk/invocations/${encodeURIComponent(body.invocationId)}/finalize`,
{
recipeNamespace: body.recipeNamespace,
recipeName: body.recipeName,
invocationId: body.invocationId,
attemptGeneration: body.attemptGeneration,
providerAttemptId: body.providerAttemptId,
providerAttemptIndex: body.providerAttemptIndex,
status: body.status,
reason: body.reason,
target: body.target,
...(body.usage ? { usage: body.usage } : {}),
},
options?.signal
)
if (!isFinalizePromptBridgeResponse(result)) {
throw new PluginWorkloadError(
'provider_unavailable',
'control-api returned an unexpected response shape for promptBridge finalization',
true
)
}
if (
result.invocationId !== body.invocationId ||
result.providerAttemptId !== body.providerAttemptId ||
result.status !== body.status
) {
throw new PluginWorkloadError(
'provider_unavailable',
'control-api returned a finalization for a different provider attempt',
false,
'outcome_unknown',
true
)
}
return result
}
async submitClientNotification(body: {
recipeNamespace: string
recipeName: string
callerRef: string
eventType: string
target?: { targetRef: string }
userRef?: string
idempotencyKey: string
notification: {
title: string
body: string
data?: Record<string, unknown>
actionRef?: { type: string; id: string; urlRef?: string }
deliveryPolicyRef?: string
correlationId?: string
}
}): Promise<SubmitClientNotificationResponse> {
const result = await this.post('/api/v1/mcp-host/plugin-workload-sdk/client-notification', body)
if (!isSubmitClientNotificationResponse(result)) {
throw new PluginWorkloadError(
'provider_unavailable',
'control-api returned an unexpected response shape for submit-client-notification',
true
)
}
return result
}
/**
* List the clientNotifications grant's allowed recipients (read-only). The
* gateway hop is a POST carrying the recipe binding in the body — same
* binding-match contract and refresh-on-401 path as submitClientNotification —
* so the workload-facing GET surfaces the authoritative allowlist without a
* recipe-baked recipients env.
*/
async listClientNotificationRecipients(body: {
recipeNamespace: string
recipeName: string
callerRef: string
}): Promise<ListClientNotificationRecipientsResponse> {
const result = await this.post(
'/api/v1/mcp-host/plugin-workload-sdk/client-notification/recipients',
body
)
if (!isListClientNotificationRecipientsResponse(result)) {
throw new PluginWorkloadError(
'provider_unavailable',
'control-api returned an unexpected response shape for list-recipients',
true
)
}
return result
}
}