## ADDED Requirements

### Requirement: AI invocation is platform-mediated

The platform SHALL expose AI invocation only through platform-owned APIs and services that use stored provider metadata and never expose raw provider credentials to plugins, platform_web, run, or API responses.

#### Scenario: Plugin invokes allowed AI purpose
- **WHEN** a plugin page submits an `ai.invoke` request with an allowed purpose and bounded input
- **THEN** the platform MUST validate the purpose, select an enabled provider through platform-owned configuration, invoke a provider client, and return a redacted AI response

#### Scenario: Raw provider credential is never returned
- **WHEN** any AI invocation succeeds or fails
- **THEN** the response MUST NOT include raw API keys, provider bearer tokens, provider base URL secrets, platform auth storage, run credentials, direct sockets, or raw host paths

### Requirement: AI purposes and payloads are validated

The platform SHALL validate invocation purpose, plugin permissions, server scope, model preference, input size, context references, and unsafe credential-like content before invoking a provider client.

#### Scenario: Undeclared purpose is denied
- **WHEN** a plugin requests an AI purpose not declared by its manifest metadata or current bridge page permissions
- **THEN** the platform MUST deny the request before provider invocation

#### Scenario: Unsafe payload is rejected
- **WHEN** an invocation payload includes raw key-like content, absolute host paths, direct sockets, or unbounded input
- **THEN** the platform MUST reject the request with a safe validation error

### Requirement: Provider invocation is mockable and bounded

The platform SHALL invoke AI through a provider client interface that supports deterministic tests without real external accounts or paid services.

#### Scenario: Mock provider returns recommendation
- **WHEN** tests or local mode use the mock provider client
- **THEN** invocation MUST return deterministic safe content, usage metadata, and optional structured recommendations without network access

#### Scenario: Provider failure is redacted
- **WHEN** the provider client returns an error
- **THEN** the platform MUST return a safe error response without provider credentials or raw transport details

### Requirement: Config suggestions remain reviewable

AI-generated configuration changes SHALL be returned as recommendations or diff previews and SHALL NOT directly dispatch run-side config write jobs.

#### Scenario: AI suggests config edit
- **WHEN** an invocation purpose requests config assistance
- **THEN** the response MAY include a proposed diff or recommendation, but the platform MUST require the separate config preview/approval workflow before dispatching a write job

### Requirement: Frontend and plugin SDK use mediated AI contracts

The frontend and plugin SDK SHALL use typed AI bridge/API contracts and SHALL NOT expose provider keys or raw provider configuration to plugin code.

#### Scenario: Plugin SDK builds AI request
- **WHEN** plugin code builds an AI invocation request
- **THEN** it MUST include purpose, request ID, scoped input, and context references while excluding raw provider credentials

#### Scenario: Browser walkthrough verifies AI request safety
- **WHEN** AI invocation UI behavior is claimed complete
- **THEN** a browser walkthrough MUST verify an AI-assisted workflow renders redacted results and does not expose raw credential markers

### Requirement: Platform-mediated AI invocation is verified

The change SHALL include backend tests, frontend tests/build, plugin tests/typecheck, browser walkthrough evidence, structure validation, and strict OpenSpec validation.

#### Scenario: Verification commands pass
- **WHEN** the change is complete
- **THEN** platform tests, platform_web tests/typecheck/build, plugin tests/typecheck, `scripts/check-structure.sh`, and `openspec validate implement-platform-mediated-ai-invocation --strict` MUST pass