OciClientConfig: support OCI Generative AI API keys (Bearer) as an authentication type

Description

OciClientConfig models four OCI IAM authentication types: API_KEY (user principal from ~/.oci/config), SECURITY_TOKEN, INSTANCE_PRINCIPAL and RESOURCE_PRINCIPAL. All of them authenticate with an OCI request signature computed by the OCI SDK.

OCI Generative AI also accepts Generative AI API keys: credentials created in the Generative AI service itself (Console Generative AI > API keys, or oci generative-ai api-key create), scoped to a compartment and a region, and sent as a plain bearer token to the OpenAI-compatible endpoint:

POST https://inference.generativeai.<region>.oci.oraclecloud.com/openai/v1/chat/completions
Authorization: Bearer sk-...

No request signing, no ~/.oci/config, no OCI SDK (Generative AI API keys, OpenAI-compatible API).

There is no way to express this credential in Agent Spec today. OciGenAiConfig.client_config must be one of the four signing types, so an agent that is meant to run with a Generative AI API key cannot be described, and falling back to OpenAiCompatibleConfig(url=..., api_key=...) loses the OCI semantics (compartment_id, serving_mode, provider, api_type, and the endpoint-specific handling the adapters apply to OCI).

Why it matters: a bearer API key is the credential shape every OpenAI-compatible client and gateway uses (the stock openai SDK, LiteLLM, opencode / models.dev provider entries, OpenRouter-style routers). I hit this while preparing the OCI Generative AI provider entries for opencode's models.dev registry and an OpenRouter provider pack, which both authenticate with an OCI_GENAI_API_KEY: an Agent Spec configuration for those deployments cannot be written, and configurations exported from such runtimes cannot round-trip.

Proposal

Add a fifth OciClientConfig specialisation:

class OciClientConfigWithGenAiApiKey(OciClientConfig):
    api_key: SensitiveField[Optional[str]] = None
    auth_type: Literal["GENAI_API_KEY"] = "GENAI_API_KEY"

• service_endpoint is inherited (the regional Generative AI inference endpoint).
• api_key is a sensitive field, exported as a $component_ref placeholder like GeminiAIStudioAuthConfig.api_key; it is optional so runtimes can load it from the OCI_GENAI_API_KEY environment variable, as the Gemini configuration does with GEMINI_API_KEY.
• The base OciClientConfig.auth_type literal gains "GENAI_API_KEY"; the component is registered in _component_registry.py, documented in the language specification (including the sensitive-fields table) and the JSON schema, with a changelog entry.
• Minimum Agent Spec version: the current development version (26.4.0), with tests for accepted and rejected export versions.
• TypeScript parity in tsagentspec: zod schema, factory, registry entries, sensitive field, version gate, tests.

Adapter impact:

• The shared OpenAI-compatible client helper of #264 (AutoGen, Agent Framework, OpenAI Agents) can turn this configuration into a plain bearer openai client, with no request signing and no oci-genai-auth dependency, and map such clients back without re-exporting the key.
• The LangGraph adapter (ChatOCIGenAI, native OCI API through langchain-oci) and the evaluation LiteLLM path have no bearer path, so they should raise a clear NotImplementedError pointing to the OpenAI-compatible runtimes.
• OciAgent should reject this client configuration: Generative AI API keys only authorize model inference, not the Agents service.

Known limits from the OCI documentation, worth stating in the docs: keys are regional and compartment-scoped; Chat Completions supports Meta Llama, xAI Grok and OpenAI gpt-oss models, the Responses API supports Grok and gpt-oss; Oracle recommends API keys for testing and early development and IAM principals for production workloads.

Environment

• pyagentspec main (26.4.0.dev0), tsagentspec main

Start by comparing OciClientConfig with GeminiAIStudioAuthConfig and tracing the Python component registry, language specification, JSON schema, and version-gate tests. Then trace the corresponding tsagentspec zod schema, factory, registry, sensitive-field, and version tests, along with the named adapter paths. Done means both implementations, documentation, changelog, export-version behavior, and adapter rejection or bearer-client behavior are covered.