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 only; it does not expose the stored secret reference.
• AIProviderTestResponse: local metadata validation result with mode=metadata; live external connectivity is deferred.
• AIProviderModelsResponse: configured model list and default model, without credentials.

Management endpoints must reject raw key-shaped values in apiKeyRef. Platform-mediated AI invocation is implemented through the platform service boundary; live external connectivity tests and remote model discovery are deferred to later changes.