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 create redacted audit/alert evidence and return a stable safe error without URL, header, key, request-body secret, or stack details. Config suggestions persist AIConfigDiffPreview with actor/server/plugin/provider/model, config version/checksum, expiry, and proposed content. Only POST /api/v1/ai/config-diffs/{id}/approve may dispatch the matching config.write job, and stale/expired/mismatched approvals are rejected.