Skip to content

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

TypeScript
34.6 KB
Raw Blame
import { afterEach, describe, expect, it, vi } from 'vitest'
import { computeGrokPolicyHash } from '@clerum/grok-provider-attempt-contract'
import { computeCodexPolicyHash } from '@clerum/llm-provider-attempt-contract'
import { CircuitBreaker } from '../domain/circuitBreaker'
import { PluginWorkloadError } from '../domain/errors'
import { replaceSdkOnlyCodexBinding } from '../sdkOnlyCodexBinding'
import { replaceSdkOnlyGrokBinding } from '../sdkOnlyGrokBinding'
import { PluginWorkloadSdkControlApiClient } from './controlApiClient'

const promptBody = {
  recipeNamespace: 'sandbox-recipes',
  recipeName: 'r1',
  callerRef: 'api',
  purpose: 'summarization',
  idempotencyKey: 'k1',
  messages: [{ role: 'user', content: 'hi' }],
}
const target = {
  targetRef: 'primary-zai',
  provider: 'zai',
  model: 'glm-5.1',
  credentialSlot: 'zai-api-key',
}

function authorizedBody(invocationId: string) {
  return {
    contractVersion: 2,
    invocationId,
    replay: false,
    providerCallRequired: true,
    status: 'in_progress',
    model: target.model,
    modelPolicy: null,
    selectedTarget: target,
    authorizedTargets: [target],
    attemptGeneration: 1,
    policyRevision: 2,
    policyHash: 'a'.repeat(64),
    // The field is required on the wire again. `null` is "this grant
    // sets no ceiling", which is the default these fixtures describe.
    maxOutputTokens: null,
  }
}

function jsonResponse(status: number, body: unknown): Response {
  return new Response(JSON.stringify(body), {
    status,
    headers: { 'Content-Type': 'application/json' },
  })
}

function makeClient(fetchImpl: typeof fetch, breaker?: CircuitBreaker) {
  return new PluginWorkloadSdkControlApiClient({
    baseUrl: 'http://gateway:8092/',
    getAccessToken: () => 'jwt-access',
    fetchImpl,
    maxRetries: 2,
    retryBaseDelayMs: 1,
    breaker,
  })
}

function installCodexBinding(model = 'gpt-5.1') {
  const binding = {
    connectionKey: 'team-plus',
    catalogRevision: 4,
    credentialRevision: 1,
    model,
    bindingHash: computeCodexPolicyHash({
      model,
      catalogRevision: 4,
      credentialRevision: 1,
      connectionKey: 'team-plus',
    }),
  }
  replaceSdkOnlyCodexBinding(binding)
  return binding
}

afterEach(() => {
  replaceSdkOnlyCodexBinding(null)
  replaceSdkOnlyGrokBinding(null)
})

describe('PluginWorkloadSdkControlApiClient', () => {
  it('posts to the gateway with the mcp-host bearer token', async () => {
    const fetchImpl = vi.fn().mockResolvedValue(jsonResponse(201, authorizedBody('inv-1')))
    const client = makeClient(fetchImpl as unknown as typeof fetch)
    const result = await client.authorizePromptBridge(promptBody)
    expect(result.invocationId).toBe('inv-1')
    const [url, init] = fetchImpl.mock.calls[0] as [string, RequestInit]
    expect(url).toBe('http://gateway:8092/api/v1/mcp-host/plugin-workload-sdk/prompt-bridge/v2')
    expect((init.headers as Record<string, string>).Authorization).toBe('Bearer jwt-access')
  })

  it('maps a structured 4xx error code to PluginWorkloadError without leaking internals', async () => {
    const fetchImpl = vi
      .fn()
      .mockResolvedValue(
        jsonResponse(429, { error: 'quota_exceeded', message: 'limit hit', retryable: false })
      )
    const client = makeClient(fetchImpl as unknown as typeof fetch)
    await expect(client.authorizePromptBridge(promptBody)).rejects.toMatchObject({
      code: 'quota_exceeded',
      retryable: false,
    })
    expect(fetchImpl).toHaveBeenCalledTimes(1) // 4xx is not retried
  })

  it('accepts identity-only bootstrap before an operator grant exists', async () => {
    const fetchImpl = vi.fn().mockResolvedValue(
      jsonResponse(200, {
        contractVersion: 2,
        supportedContractVersions: [2],
        targetAwarePromptBridge: true,
        attemptLedger: true,
        credentialTickets: true,
        policyState: 'missing',
        policyRevision: 0,
        policyHash: null,
        defaultTargetRef: null,
        defaultProvider: null,
        defaultModel: null,
        v2Ready: false,
        clientNotificationsPolicyState: 'missing',
        clientNotificationsReady: false,
      })
    )
    const client = makeClient(fetchImpl as unknown as typeof fetch)

    await expect(client.verifyPromptBridgeBootstrapV2('openai', 'gpt-5.4-mini')).resolves.toEqual({
      ready: true,
      contractVersion: 2,
      provider: 'openai',
      model: 'gpt-5.4-mini',
      policyReady: false,
      policyState: 'missing',
      policyReason: 'grant_missing',
      clientNotificationsPolicyReady: false,
      clientNotificationsPolicyState: 'missing',
      clientNotificationsPolicyReason: 'grant_missing',
    })
    expect(fetchImpl).toHaveBeenCalledWith(
      'http://gateway:8092/api/v1/mcp-host/plugin-workload-sdk/capabilities',
      expect.objectContaining({ method: 'GET' })
    )
  })

  it('requires reservation-only Codex capabilities before marking policy ready', async () => {
    installCodexBinding()
    const fetchImpl = vi.fn().mockResolvedValue(
      jsonResponse(200, {
        contractVersion: 3,
        supportedContractVersions: [2, 3],
        reservationOnlyOauthBroker: true,
        targetAwarePromptBridge: true,
        attemptLedger: true,
        credentialTickets: true,
        policyState: 'active',
        policyRevision: 2,
        policyHash: 'a'.repeat(64),
        defaultTargetRef: 'codex-primary',
        defaultProvider: 'codex-subscription',
        defaultModel: 'gpt-5.1',
        defaultConnectionRef: 'team-plus',
        v2Ready: true,
        clientNotificationsPolicyState: 'missing',
        clientNotificationsReady: false,
      })
    )
    const client = makeClient(fetchImpl as unknown as typeof fetch)

    await expect(
      client.verifyPromptBridgeBootstrapV2('codex-subscription', 'gpt-5.1')
    ).resolves.toMatchObject({
      ready: true,
      contractVersion: 3,
      policyReady: true,
      policyState: 'active',
      codexBindingReady: true,
    })
  })

  it('keeps Codex policy not ready when an old API advertises contract v2', async () => {
    installCodexBinding()
    const fetchImpl = vi.fn().mockResolvedValue(
      jsonResponse(200, {
        contractVersion: 2,
        supportedContractVersions: [2, 3],
        targetAwarePromptBridge: true,
        attemptLedger: true,
        credentialTickets: true,
        policyState: 'active',
        policyRevision: 2,
        policyHash: 'a'.repeat(64),
        defaultTargetRef: 'codex-primary',
        defaultProvider: 'codex-subscription',
        defaultModel: 'gpt-5.1',
        defaultConnectionRef: 'team-plus',
        v2Ready: true,
        clientNotificationsPolicyState: 'missing',
        clientNotificationsReady: false,
      })
    )
    const client = makeClient(fetchImpl as unknown as typeof fetch)

    await expect(
      client.verifyPromptBridgeBootstrapV2('codex-subscription', 'gpt-5.1')
    ).resolves.toMatchObject({
      ready: true,
      contractVersion: 3,
      policyReady: false,
      policyReason: 'codex_execution_binding_missing',
      codexBindingReady: false,
    })
  })

  // #533 acceptance criterion 2 — the binding must also be tied to the catalog
  // and credential revisions. They are authoritative on control-api, so the
  // comparison exists only when the peer publishes them; these five cases pin
  // every combination, including the deliberate mixed-binary compromise.
  const codexCapabilities = (extra: Record<string, unknown>) => ({
    contractVersion: 3,
    supportedContractVersions: [2, 3],
    reservationOnlyOauthBroker: true,
    targetAwarePromptBridge: true,
    attemptLedger: true,
    credentialTickets: true,
    policyState: 'active',
    policyRevision: 2,
    policyHash: 'a'.repeat(64),
    defaultTargetRef: 'codex-primary',
    defaultProvider: 'codex-subscription',
    defaultModel: 'gpt-5.1',
    defaultConnectionRef: 'team-plus',
    v2Ready: true,
    clientNotificationsPolicyState: 'missing',
    clientNotificationsReady: false,
    ...extra,
  })

  it('marks the Codex binding ready when the published revisions match it', async () => {
    installCodexBinding()
    const fetchImpl = vi.fn().mockResolvedValue(
      jsonResponse(
        200,
        codexCapabilities({
          codexBindingRevisions: true,
          defaultCatalogRevision: 4,
          defaultCredentialRevision: 1,
        })
      )
    )
    const client = makeClient(fetchImpl as unknown as typeof fetch)

    await expect(
      client.verifyPromptBridgeBootstrapV2('codex-subscription', 'gpt-5.1')
    ).resolves.toMatchObject({ policyReady: true, codexBindingReady: true })
  })

  it('marks the Grok binding ready from the Grok slot, not the Codex slot', async () => {
    replaceSdkOnlyGrokBinding({
      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 fetchImpl = vi.fn().mockResolvedValue(
      jsonResponse(
        200,
        codexCapabilities({
          defaultProvider: 'grok-subscription',
          defaultModel: 'grok-4.6',
          defaultConnectionRef: 'team-grok',
          defaultTargetRef: 'grok-primary',
          reservationOnlyOauthBroker: true,
          contractVersion: 3,
          supportedContractVersions: [2, 3],
          codexBindingRevisions: true,
          defaultCatalogRevision: 5,
          defaultCredentialRevision: 2,
        })
      )
    )
    const client = makeClient(fetchImpl as unknown as typeof fetch)
    await expect(
      client.verifyPromptBridgeBootstrapV2('grok-subscription', 'grok-4.6')
    ).resolves.toMatchObject({
      policyReady: true,
      bindingReady: true,
    })
  })

  it('does not treat a Codex binding as a Grok execution proof', async () => {
    installCodexBinding()
    const fetchImpl = vi.fn().mockResolvedValue(
      jsonResponse(
        200,
        codexCapabilities({
          defaultProvider: 'grok-subscription',
          defaultModel: 'grok-4.6',
          defaultConnectionRef: 'team-grok',
          defaultTargetRef: 'grok-primary',
          reservationOnlyOauthBroker: true,
          contractVersion: 3,
          supportedContractVersions: [2, 3],
          codexBindingRevisions: true,
          defaultCatalogRevision: 5,
          defaultCredentialRevision: 2,
        })
      )
    )
    const client = makeClient(fetchImpl as unknown as typeof fetch)
    await expect(
      client.verifyPromptBridgeBootstrapV2('grok-subscription', 'grok-4.6')
    ).resolves.toMatchObject({
      policyReady: false,
      bindingReady: false,
      policyReason: 'execution_binding_missing',
    })
  })

  it('refuses a binding whose catalog revision is behind the published one', async () => {
    installCodexBinding()
    const fetchImpl = vi.fn().mockResolvedValue(
      jsonResponse(
        200,
        codexCapabilities({
          codexBindingRevisions: true,
          defaultCatalogRevision: 5,
          defaultCredentialRevision: 1,
        })
      )
    )
    const client = makeClient(fetchImpl as unknown as typeof fetch)

    await expect(
      client.verifyPromptBridgeBootstrapV2('codex-subscription', 'gpt-5.1')
    ).resolves.toMatchObject({
      policyReady: false,
      policyReason: 'codex_execution_binding_missing',
      codexBindingReady: false,
    })
  })

  it('refuses a binding whose credential revision is behind the published one', async () => {
    installCodexBinding()
    const fetchImpl = vi.fn().mockResolvedValue(
      jsonResponse(
        200,
        codexCapabilities({
          codexBindingRevisions: true,
          defaultCatalogRevision: 4,
          defaultCredentialRevision: 2,
        })
      )
    )
    const client = makeClient(fetchImpl as unknown as typeof fetch)

    await expect(
      client.verifyPromptBridgeBootstrapV2('codex-subscription', 'gpt-5.1')
    ).resolves.toMatchObject({
      policyReady: false,
      policyReason: 'codex_execution_binding_missing',
      codexBindingReady: false,
    })
  })

  it('refuses the binding when the peer claims revisions but omits one', async () => {
    // A partial deploy must not read as agreement: the flag is the peer's
    // promise to send both values, so a missing one is a broken promise.
    installCodexBinding()
    const fetchImpl = vi
      .fn()
      .mockResolvedValue(
        jsonResponse(
          200,
          codexCapabilities({ codexBindingRevisions: true, defaultCredentialRevision: 1 })
        )
      )
    const client = makeClient(fetchImpl as unknown as typeof fetch)

    await expect(
      client.verifyPromptBridgeBootstrapV2('codex-subscription', 'gpt-5.1')
    ).resolves.toMatchObject({
      policyReady: false,
      policyReason: 'codex_execution_binding_missing',
      codexBindingReady: false,
    })
  })

  it('keeps the binding ready against an API that predates the revision fields', async () => {
    // Deliberate: demanding a field an older control-api cannot emit would
    // fail closed across a mixed-binary window (the #540 shape). This is not
    // unfenced — authorize and redeem still reject a stale revision — so the
    // cost is that a stale binding surfaces at the first prompt instead of at
    // reconcile. Do not "fix" this into a fail-closed branch.
    installCodexBinding()
    const fetchImpl = vi
      .fn()
      .mockResolvedValue(jsonResponse(200, codexCapabilities({ defaultCatalogRevision: 999 })))
    const client = makeClient(fetchImpl as unknown as typeof fetch)

    await expect(
      client.verifyPromptBridgeBootstrapV2('codex-subscription', 'gpt-5.1')
    ).resolves.toMatchObject({ policyReady: true, codexBindingReady: true })
  })

  // The hand-built fixtures only ever used catalog revisions
  // {4,5,7,999} and never 0 — which is the schema DEFAULT for a never-synced
  // catalog and exactly the value the inverted bounds rejected. These pin the
  // real CHECK constraints of codex_subscription_connections:
  //   catalog_revision    BIGINT NOT NULL DEFAULT 0 CHECK (>= 0)
  //   credential_revision BIGINT NOT NULL DEFAULT 1 CHECK (>= 1)
  it('accepts a never-synced peer publishing catalog revision 0 and reports the binding not ready', async () => {
    installCodexBinding()
    const fetchImpl = vi.fn().mockResolvedValue(
      jsonResponse(
        200,
        codexCapabilities({
          codexBindingRevisions: true,
          defaultCatalogRevision: 0,
          defaultCredentialRevision: 1,
        })
      )
    )
    const client = makeClient(fetchImpl as unknown as typeof fetch)

    await expect(
      client.verifyPromptBridgeBootstrapV2('codex-subscription', 'gpt-5.1')
    ).resolves.toMatchObject({
      policyReady: false,
      policyReason: 'codex_execution_binding_missing',
      codexBindingReady: false,
    })
  })

  it('rejects a credential revision below the schema floor as a protocol mismatch', async () => {
    installCodexBinding()
    const fetchImpl = vi.fn().mockResolvedValue(
      jsonResponse(
        200,
        codexCapabilities({
          codexBindingRevisions: true,
          defaultCatalogRevision: 4,
          defaultCredentialRevision: 0,
        })
      )
    )
    const client = makeClient(fetchImpl as unknown as typeof fetch)

    await expect(
      client.verifyPromptBridgeBootstrapV2('codex-subscription', 'gpt-5.1')
    ).rejects.toMatchObject({ code: 'protocol_mismatch' })
  })

  it('refuses the binding when the peer claims revisions but omits both', async () => {
    // A revoked or absent connection now keeps the flag and drops only
    // the numbers, so this is the branch a live control-api takes for a
    // connection that cannot back any binding.
    installCodexBinding()
    const fetchImpl = vi
      .fn()
      .mockResolvedValue(jsonResponse(200, codexCapabilities({ codexBindingRevisions: true })))
    const client = makeClient(fetchImpl as unknown as typeof fetch)

    await expect(
      client.verifyPromptBridgeBootstrapV2('codex-subscription', 'gpt-5.1')
    ).resolves.toMatchObject({
      policyReady: false,
      policyReason: 'codex_execution_binding_missing',
      codexBindingReady: false,
    })
  })

  it('keeps request-time policy readiness separate from identity bootstrap', async () => {
    const fetchImpl = vi.fn().mockResolvedValue(
      jsonResponse(200, {
        contractVersion: 2,
        supportedContractVersions: [2],
        targetAwarePromptBridge: true,
        attemptLedger: true,
        credentialTickets: true,
        policyState: 'missing',
        policyRevision: 0,
        policyHash: null,
        defaultTargetRef: null,
        defaultProvider: null,
        defaultModel: null,
        v2Ready: false,
        clientNotificationsPolicyState: 'missing',
        clientNotificationsReady: false,
      })
    )
    const client = makeClient(fetchImpl as unknown as typeof fetch)

    await expect(client.ensurePromptBridgeCapabilities()).rejects.toMatchObject({
      code: 'provider_policy_denied',
      retryable: false,
    })
  })

  it('proves provider-free clientNotifications readiness from the capabilities contract', async () => {
    const fetchImpl = vi.fn().mockResolvedValue(
      jsonResponse(200, {
        contractVersion: 2,
        supportedContractVersions: [2],
        targetAwarePromptBridge: true,
        attemptLedger: true,
        credentialTickets: true,
        policyState: 'missing',
        policyRevision: 0,
        policyHash: null,
        defaultTargetRef: null,
        defaultProvider: null,
        defaultModel: null,
        v2Ready: false,
        clientNotificationsPolicyState: 'active',
        clientNotificationsReady: true,
      })
    )
    const client = makeClient(fetchImpl as unknown as typeof fetch)

    await expect(client.verifyClientNotificationsBootstrap()).resolves.toEqual({
      ready: true,
      contractVersion: 2,
      policyReady: true,
      policyState: 'active',
    })
  })

  it('accepts a policy-only authorization envelope and leaves ticket issuance to the attempt path', async () => {
    const fetchImpl = vi.fn().mockResolvedValue(jsonResponse(201, authorizedBody('inv-1')))
    const client = makeClient(fetchImpl as unknown as typeof fetch)
    await expect(client.authorizePromptBridge(promptBody)).resolves.toMatchObject({
      invocationId: 'inv-1',
      authorizedTargets: [target],
    })
  })

  it('rejects a response missing the v2 provider-call disposition', async () => {
    const { providerCallRequired: _omitted, ...incompleteBody } =
      authorizedBody('legacy-invocation')
    const fetchImpl = vi.fn().mockResolvedValue(jsonResponse(201, incompleteBody))
    const client = makeClient(fetchImpl as unknown as typeof fetch)
    await expect(client.authorizePromptBridge(promptBody)).rejects.toMatchObject({
      code: 'provider_unavailable',
    })
  })

  it('serializes provider and target selectors without supplying a host default', async () => {
    const fetchImpl = vi.fn().mockResolvedValue(jsonResponse(201, authorizedBody('inv-1')))
    const client = makeClient(fetchImpl as unknown as typeof fetch)
    await client.authorizePromptBridge({
      ...promptBody,
      provider: 'zai',
      model: 'glm-5.1',
      targetRef: 'primary-zai',
    })
    const init = fetchImpl.mock.calls[0]?.[1] as RequestInit
    expect(JSON.parse(String(init.body))).toMatchObject({
      provider: 'zai',
      model: 'glm-5.1',
      targetRef: 'primary-zai',
    })
  })

  it('reissues a ticket bound to the authorized recipe, invocation, target, and policy snapshot', async () => {
    const fetchImpl = vi.fn().mockResolvedValue(
      jsonResponse(201, {
        invocationId: 'inv-1',
        attemptGeneration: 1,
        providerAttemptId: 'attempt-1',
        providerAttemptIndex: 1,
        targetRef: target.targetRef,
        credentialTicket: 'fresh-signed-ticket',
        policyRevision: 2,
        policyHash: 'a'.repeat(64),
        expiresInSeconds: 60,
      })
    )
    const client = makeClient(fetchImpl as unknown as typeof fetch)

    await expect(
      client.reissuePromptBridgeCredentialTicket({
        recipeNamespace: 'sandbox-recipes',
        recipeName: 'r1',
        invocationId: 'inv-1',
        attemptGeneration: 1,
        target,
        policyRevision: 2,
        policyHash: 'a'.repeat(64),
      })
    ).resolves.toMatchObject({ credentialTicket: 'fresh-signed-ticket' })

    const [url, init] = fetchImpl.mock.calls[0] as [string, RequestInit]
    expect(url).toBe(
      'http://gateway:8092/api/v1/mcp-host/plugin-workload-sdk/prompt-bridge/credential-ticket'
    )
    expect(JSON.parse(String(init.body))).toEqual({
      recipeNamespace: 'sandbox-recipes',
      recipeName: 'r1',
      invocationId: 'inv-1',
      targetRef: target.targetRef,
      attemptGeneration: 1,
    })
  })

  it('rejects a reissued ticket that does not match the original authorization snapshot', async () => {
    const fetchImpl = vi.fn().mockResolvedValue(
      jsonResponse(201, {
        invocationId: 'inv-1',
        attemptGeneration: 1,
        providerAttemptId: 'attempt-1',
        providerAttemptIndex: 1,
        targetRef: 'different-target',
        credentialTicket: 'fresh-signed-ticket',
        policyRevision: 2,
        policyHash: 'a'.repeat(64),
        expiresInSeconds: 60,
      })
    )
    const client = makeClient(fetchImpl as unknown as typeof fetch)
    await expect(
      client.reissuePromptBridgeCredentialTicket({
        recipeNamespace: 'sandbox-recipes',
        recipeName: 'r1',
        invocationId: 'inv-1',
        attemptGeneration: 1,
        target,
        policyRevision: 2,
        policyHash: 'a'.repeat(64),
      })
    ).rejects.toMatchObject({ code: 'provider_unavailable', retryable: false })
  })

  it('retries 5xx and returns provider_unavailable after exhausting retries', async () => {
    const fetchImpl = vi.fn().mockResolvedValue(jsonResponse(503, {}))
    const client = makeClient(fetchImpl as unknown as typeof fetch)
    await expect(client.authorizePromptBridge(promptBody)).rejects.toMatchObject({
      code: 'provider_unavailable',
      retryable: true,
    })
    expect(fetchImpl).toHaveBeenCalledTimes(3) // initial + 2 retries
  })

  it('retries network failures and succeeds on a later attempt', async () => {
    const fetchImpl = vi
      .fn()
      .mockRejectedValueOnce(new Error('ECONNREFUSED'))
      .mockResolvedValueOnce(jsonResponse(201, authorizedBody('inv-2')))
    const client = makeClient(fetchImpl as unknown as typeof fetch)
    const result = await client.authorizePromptBridge(promptBody)
    expect(result.invocationId).toBe('inv-2')
    expect(fetchImpl).toHaveBeenCalledTimes(2)
  })

  it('short-circuits with provider_unavailable while the breaker is open', async () => {
    let t = 0
    const breaker = new CircuitBreaker({ now: () => t, minSamples: 2 })
    breaker.record(false)
    breaker.record(false)
    const fetchImpl = vi.fn()
    const client = makeClient(fetchImpl as unknown as typeof fetch, breaker)
    await expect(client.authorizePromptBridge(promptBody)).rejects.toMatchObject({
      code: 'provider_unavailable',
      retryable: true,
    })
    expect(fetchImpl).not.toHaveBeenCalled()
  })

  it('maps 401 to unauthorized', async () => {
    const fetchImpl = vi.fn().mockResolvedValue(jsonResponse(401, { error: 'Unauthorized' }))
    const client = makeClient(fetchImpl as unknown as typeof fetch)
    await expect(client.authorizePromptBridge(promptBody)).rejects.toMatchObject({
      code: 'unauthorized',
    })
  })

  describe('refresh-on-401 (runtime-token durability)', () => {
    const successBody = authorizedBody('inv-ok')

    function makeRefreshingClient(
      fetchImpl: typeof fetch,
      refreshOnUnauthorized: () => Promise<void>
    ) {
      return new PluginWorkloadSdkControlApiClient({
        baseUrl: 'http://gateway:8092/',
        getAccessToken: () => 'jwt-access',
        refreshOnUnauthorized,
        fetchImpl,
        maxRetries: 2,
        retryBaseDelayMs: 1,
      })
    }

    it('refreshes once on a 401 then retries and succeeds with the fresh token', async () => {
      const fetchImpl = vi
        .fn()
        .mockResolvedValueOnce(jsonResponse(401, { error: 'Unauthorized' }))
        .mockResolvedValueOnce(jsonResponse(201, successBody))
      const refresh = vi.fn().mockResolvedValue(undefined)
      const client = makeRefreshingClient(fetchImpl as unknown as typeof fetch, refresh)
      const result = await client.authorizePromptBridge(promptBody)
      expect(result.invocationId).toBe('inv-ok')
      expect(refresh).toHaveBeenCalledTimes(1)
      expect(fetchImpl).toHaveBeenCalledTimes(2) // original 401 + post-refresh retry
    })

    it('propagates unauthorized when the retry also 401s (bad credential, no loop)', async () => {
      const fetchImpl = vi.fn().mockResolvedValue(jsonResponse(401, { error: 'Unauthorized' }))
      const refresh = vi.fn().mockResolvedValue(undefined)
      const client = makeRefreshingClient(fetchImpl as unknown as typeof fetch, refresh)
      await expect(client.authorizePromptBridge(promptBody)).rejects.toMatchObject({
        code: 'unauthorized',
      })
      expect(refresh).toHaveBeenCalledTimes(1) // exactly one refresh, then surface the error
    })

    it('coalesces concurrent 401s onto a single refresh (refresh JTI burned once)', async () => {
      let attempts = 0
      const fetchImpl = vi.fn().mockImplementation(() => {
        attempts += 1
        // The two concurrent originals 401; both post-refresh retries succeed.
        return Promise.resolve(
          attempts <= 2
            ? jsonResponse(401, { error: 'Unauthorized' })
            : jsonResponse(201, successBody)
        )
      })
      let release: () => void = () => {}
      const gate = new Promise<void>(res => {
        release = res
      })
      const refresh = vi.fn().mockImplementation(() => gate)
      const client = makeRefreshingClient(fetchImpl as unknown as typeof fetch, refresh)
      const p1 = client.authorizePromptBridge(promptBody)
      const p2 = client.authorizePromptBridge(promptBody)
      // Let both originals 401 and reach triggerRefresh before the refresh resolves.
      await new Promise(res => setTimeout(res, 10))
      release()
      const [r1, r2] = await Promise.all([p1, p2])
      expect(r1.invocationId).toBe('inv-ok')
      expect(r2.invocationId).toBe('inv-ok')
      expect(refresh).toHaveBeenCalledTimes(1) // coalesced, not once per caller
    })

    it('still surfaces 401 as unauthorized when no refresh hook is wired', async () => {
      const fetchImpl = vi.fn().mockResolvedValue(jsonResponse(401, { error: 'Unauthorized' }))
      const client = makeClient(fetchImpl as unknown as typeof fetch)
      await expect(client.authorizePromptBridge(promptBody)).rejects.toMatchObject({
        code: 'unauthorized',
      })
      expect(fetchImpl).toHaveBeenCalledTimes(1) // no refresh, no retry
    })
  })

  it('reportInvocationStatus surfaces a rejected terminal acknowledgement', async () => {
    const fetchImpl = vi.fn().mockResolvedValue(jsonResponse(500, {}))
    const client = makeClient(fetchImpl as unknown as typeof fetch)
    await expect(
      client.reportInvocationStatus('inv-1', 'sandbox-recipes', 'r1', 'complete', 1)
    ).rejects.toMatchObject({ code: 'provider_unavailable', retryable: true })
  })

  it('finalizes one provider attempt with an idempotent exact usage receipt', async () => {
    const fetchImpl = vi.fn().mockResolvedValue(
      jsonResponse(201, {
        invocationId: 'inv-1',
        providerAttemptId: 'attempt-1',
        status: 'complete',
        outcome: 'exact',
        idempotent: false,
        usageAccepted: true,
      })
    )
    const client = makeClient(fetchImpl as unknown as typeof fetch)
    const result = await client.finalizePromptBridge({
      recipeNamespace: 'sandbox-recipes',
      recipeName: 'r1',
      invocationId: 'inv-1',
      attemptGeneration: 1,
      providerAttemptId: 'attempt-1',
      providerAttemptIndex: 1,
      status: 'complete',
      reason: 'provider_completed',
      target,
      usage: {
        llmSecretName: 'zai-api-key',
        callerRef: 'api',
        fallbackUsed: false,
        attemptCount: 1,
        inputTokens: 3,
        outputTokens: 4,
      },
    })
    expect(result).toMatchObject({ outcome: 'exact', usageAccepted: true })
    const [url, init] = fetchImpl.mock.calls[0] as [string, RequestInit]
    expect(url).toBe(
      'http://gateway:8092/api/v1/mcp-host/plugin-workload-sdk/invocations/inv-1/finalize'
    )
    expect(JSON.parse(String(init.body))).toMatchObject({
      invocationId: 'inv-1',
      providerAttemptId: 'attempt-1',
      status: 'complete',
      usage: { inputTokens: 3, outputTokens: 4 },
    })
  })

  it('surfaces ledger_pending as the retryable-with-reason finalize triple', async () => {
    // The handler retries a finalize ONLY on this exact triple. If control-api
    // ever stops sending `reason`, or the client stops mapping it, the retry
    // silently disappears — so the triple is asserted end to end here.
    const fetchImpl = vi.fn().mockResolvedValue(
      jsonResponse(409, {
        error: 'provider_unavailable',
        message: 'linked Codex attempt has not finalized usage yet',
        retryable: true,
        reason: 'provider_unavailable',
      })
    )
    const client = makeClient(fetchImpl as unknown as typeof fetch)
    const failure = await client
      .finalizePromptBridge({
        recipeNamespace: 'sandbox-recipes',
        recipeName: 'r1',
        invocationId: 'inv-1',
        attemptGeneration: 1,
        providerAttemptId: 'attempt-1',
        providerAttemptIndex: 1,
        status: 'complete',
        reason: 'provider_completed',
        target,
      })
      .catch((err: unknown) => err)
    expect(failure).toBeInstanceOf(PluginWorkloadError)
    expect(failure).toMatchObject({
      code: 'provider_unavailable',
      retryable: true,
      reason: 'provider_unavailable',
    })
    // A 409 is not retried by the transport itself; the ledger retry lives in
    // the handler, where the deadline can bound it.
    expect(fetchImpl).toHaveBeenCalledTimes(1)
  })

  it('threads a caller deadline into the finalize request and stops retrying once aborted', async () => {
    const controller = new AbortController()
    const fetchImpl = vi.fn().mockResolvedValue(
      jsonResponse(201, {
        invocationId: 'inv-1',
        providerAttemptId: 'attempt-1',
        status: 'complete',
        outcome: 'exact',
        idempotent: false,
        usageAccepted: true,
      })
    )
    const client = makeClient(fetchImpl as unknown as typeof fetch)
    await client.finalizePromptBridge(
      {
        recipeNamespace: 'sandbox-recipes',
        recipeName: 'r1',
        invocationId: 'inv-1',
        attemptGeneration: 1,
        providerAttemptId: 'attempt-1',
        providerAttemptIndex: 1,
        status: 'complete',
        reason: 'provider_completed',
        target,
      },
      { signal: controller.signal }
    )
    const [, init] = fetchImpl.mock.calls[0] as [string, RequestInit]
    expect(init.signal).toBeInstanceOf(AbortSignal)
    expect(init.signal?.aborted).toBe(false)

    // An already-expired deadline must not buy a single transport attempt: the
    // AbortError would otherwise be swallowed by the network-retry branch.
    const abortedFetch = vi.fn()
    const abortedClient = makeClient(abortedFetch as unknown as typeof fetch)
    await expect(
      abortedClient.finalizePromptBridge(
        {
          recipeNamespace: 'sandbox-recipes',
          recipeName: 'r1',
          invocationId: 'inv-1',
          attemptGeneration: 1,
          providerAttemptId: 'attempt-1',
          providerAttemptIndex: 1,
          status: 'complete',
          reason: 'provider_completed',
          target,
        },
        { signal: AbortSignal.abort() }
      )
    ).rejects.toMatchObject({ code: 'provider_unavailable', retryable: true })
    expect(abortedFetch).not.toHaveBeenCalled()
  })

  it('submitClientNotification maps event_type_not_allowed', async () => {
    const fetchImpl = vi
      .fn()
      .mockResolvedValue(
        jsonResponse(403, { error: 'event_type_not_allowed', message: 'nope', retryable: false })
      )
    const client = makeClient(fetchImpl as unknown as typeof fetch)
    await expect(
      client.submitClientNotification({
        recipeNamespace: 'sandbox-recipes',
        recipeName: 'r1',
        callerRef: 'api',
        eventType: 'x.y',
        target: { targetRef: 'team.sales' },
        idempotencyKey: 'k2',
        notification: { title: 't', body: 'b' },
      })
    ).rejects.toBeInstanceOf(PluginWorkloadError)
  })

  describe('listClientNotificationRecipients', () => {
    const recipientsBody = {
      recipeNamespace: 'sandbox-recipes',
      recipeName: 'r1',
      callerRef: 'api',
    }

    it('posts the recipe binding and returns the resolved recipient list', async () => {
      const fetchImpl = vi.fn().mockResolvedValue(
        jsonResponse(200, {
          recipients: [{ userRef: 'u-1', displayName: 'Ada Lovelace' }],
        })
      )
      const client = makeClient(fetchImpl as unknown as typeof fetch)
      const result = await client.listClientNotificationRecipients(recipientsBody)
      expect(result.recipients).toEqual([{ userRef: 'u-1', displayName: 'Ada Lovelace' }])
      const [url, init] = fetchImpl.mock.calls[0] as [string, RequestInit]
      expect(url).toBe(
        'http://gateway:8092/api/v1/mcp-host/plugin-workload-sdk/client-notification/recipients'
      )
      expect((init.headers as Record<string, string>).Authorization).toBe('Bearer jwt-access')
    })

    it('rejects an unexpected response shape as provider_unavailable', async () => {
      const fetchImpl = vi
        .fn()
        .mockResolvedValue(jsonResponse(200, { recipients: [{ userRef: 'u-1' }] }))
      const client = makeClient(fetchImpl as unknown as typeof fetch)
      await expect(client.listClientNotificationRecipients(recipientsBody)).rejects.toMatchObject({
        code: 'provider_unavailable',
      })
    })

    it('refreshes once on a 401 then retries (shares the durable refresh path)', async () => {
      const fetchImpl = vi
        .fn()
        .mockResolvedValueOnce(jsonResponse(401, { error: 'Unauthorized' }))
        .mockResolvedValueOnce(jsonResponse(200, { recipients: [] }))
      const refresh = vi.fn().mockResolvedValue(undefined)
      const client = new PluginWorkloadSdkControlApiClient({
        baseUrl: 'http://gateway:8092/',
        getAccessToken: () => 'jwt-access',
        refreshOnUnauthorized: refresh,
        fetchImpl: fetchImpl as unknown as typeof fetch,
        maxRetries: 2,
        retryBaseDelayMs: 1,
      })
      const result = await client.listClientNotificationRecipients(recipientsBody)
      expect(result.recipients).toEqual([])
      expect(refresh).toHaveBeenCalledTimes(1)
      expect(fetchImpl).toHaveBeenCalledTimes(2)
    })
  })
})