browser/openspec/changes/implement-ai-provider-management/specs/ai-provider-management/spec.md

ADDED Requirements

Requirement: AI providers can be managed through platform APIs

The platform SHALL expose AI provider management APIs for create, list, detail, update, enable/disable, configuration test, and configured model listing.

Scenario: Provider is updated

• WHEN a client sends a valid provider update request to an existing AI provider
• THEN the platform MUST validate the request, persist the metadata through service.Core, and return a redacted AIProviderResponse

Scenario: Provider status is changed

• WHEN a client enables or disables an existing AI provider through the status action route
• THEN the platform MUST persist the requested status and return a redacted AIProviderResponse

Scenario: Provider configuration is tested

• WHEN a client tests an existing AI provider
• THEN the platform MUST validate stored metadata locally and return a named test result DTO without contacting external AI services

Scenario: Provider model list is requested

• WHEN a client requests configured models for an existing AI provider
• THEN the platform MUST return the provider ID, default model, and configured model names without exposing credentials

Requirement: AI provider management preserves secret boundaries

AI provider management SHALL reject raw key material in request fields and SHALL never expose raw API keys in API responses or frontend-visible types.

Scenario: Raw key is submitted during update

• WHEN a create or update request includes raw key material instead of a secret reference in apiKeyRef
• THEN the platform MUST reject the request with a validation error and MUST NOT persist the provider

Scenario: Provider is returned to UI

• WHEN the backend or frontend API client returns provider data
• THEN the response/type MUST include apiKeyRef only and MUST NOT include apiKey, rawApiKey, or equivalent raw credential fields

Requirement: AI provider service owns management invariants

The platform service layer SHALL own AI provider update, status, local test, and model-list behavior rather than implementing those rules directly in HTTP handlers.

Scenario: Management handler receives request

• WHEN an AI provider management HTTP handler accepts a request
• THEN it MUST decode named DTOs, call service.Core, and encode named DTO responses

Scenario: Missing provider is managed

• WHEN a management action targets a missing provider ID
• THEN the platform MUST return a stable 404 JSON error response

Requirement: AI provider console page is functional

The management console SHALL replace the placeholder AI provider page with a functional operational view for configured providers.

Scenario: Operator opens AI provider page

• WHEN the AI provider page renders
• THEN it MUST show provider counts, status distribution, configured model counts, and a provider table

Scenario: Operator edits provider form

• WHEN an operator creates or edits a provider through the page form
• THEN the page MUST submit named API requests and refresh or update the provider list without displaying raw key material

Scenario: Operator uses provider actions

• WHEN an operator triggers enable/disable, test, or model-list actions
• THEN the page MUST call the matching API client methods and display the redacted result state

Requirement: Frontend contracts are centralized

The frontend SHALL keep AI provider API types and client methods in platform_web/api and SHALL keep shared UI contracts out of page-local hidden types.

Scenario: Page consumes provider data

• WHEN AiProvidersPage needs provider data or actions
• THEN it MUST use named API types and PlatformApiClient methods instead of inline fetch contracts

Scenario: Frontend tests inspect provider types

• WHEN frontend tests check provider response shapes
• THEN they MUST confirm raw key fields are absent from returned provider data

Requirement: AI provider management is verified end to end

The change SHALL include backend API/service tests, frontend tests/build, a browser walkthrough, structure validation, and strict OpenSpec validation.

Scenario: Verification commands run

• WHEN the change is complete
• THEN go test ./... from platform/, frontend tests/build, scripts/check-structure.sh, and openspec validate implement-ai-provider-management --strict MUST pass

Scenario: Browser walkthrough runs

• WHEN frontend AI provider page behavior is claimed complete
• THEN a browser walkthrough MUST verify the page renders, exposes the AI provider workflow, and does not show raw credential fields