# 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. 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.