browser/platform/protocol/ai-provider-contracts.md

AI Provider Contracts

AI providers are platform-managed model endpoints used by plugins through scoped platform capabilities.

AIProviderConfig

• id: provider ID.
• name: display name.
• kind: provider kind.
• baseUrl: base URL or relay URL.
• apiKeyRef: secret reference.
• models: allowed model list.
• defaultModel: default model.
• relayMode: direct, relay, or local.
• timeoutMs: timeout.
• status: active, disabled, or error.
• redactionPolicy: redaction policy key.

AIInvocationRequest

• providerId: selected provider.
• purpose: scoped purpose such as config.suggest or logs.diagnose.
• serverInstanceId: optional server context.
• pluginId: caller plugin.
• inputRef: artifact or bounded structured input.
• model: optional model override.

AI invocation responses must be bounded and must not include raw provider credentials. Config write suggestions must be presented as a diff or recommendation before dispatching run jobs.

Management API Contracts

• AIProviderCreateRequest: create provider metadata with apiKeyRef, never raw key material.
• AIProviderUpdateRequest: replace editable provider metadata while preserving status through the service layer.
• AIProviderStatusRequest: set provider status to active or disabled.
• AIProviderResponse: redacted provider response with apiKeyConfigured and baseUrlConfigured only; it does not expose the stored secret reference or provider endpoint.
• AIProviderTestResponse: local metadata validation result with mode=metadata; live external connectivity is deferred.
• AIProviderModelsResponse: configured model list and default model, without credentials.

Management endpoints reject raw key-shaped values in apiKeyRef. In live mode Platform resolves env://NAME or secret://providers/<id> inside the service boundary and invokes OpenAI-compatible, OpenAI, Claude, Gemini, Ollama, or custom HTTP providers with bounded requests. Local debug uses explicit mock mode.

Provider failures return a stable safe error without URL, header, key, request-body secret, or stack details. A config suggestion response includes the proposed content plus configExecution metadata for the bounded config.write job that Platform dispatches immediately after the current config version/checksum, permissions, runtime binding, and content-safety checks pass. The response contains the job ID and target key so the caller can follow execution logs without receiving provider credentials.