## Context

AI provider credentials and base URLs belong to `platform/`, while plugin pages may request AI assistance only through platform-mediated capabilities. AI-suggested config changes must be reviewable before any run-side write job is dispatched. This change introduces the invocation boundary and keeps provider clients mockable so implementation and tests do not require real keys or external services.

## Goals / Non-Goals

**Goals:**

- Add AI invocation request/response contracts with plugin, server, purpose, model preference, input, and review context.
- Enforce allowed purposes from plugin manifest metadata and platform policy.
- Route invocation through platform-owned provider configuration and a provider client interface.
- Return bounded recommendations, safe text, structured diff suggestions, and usage metadata.
- Ensure config-writing suggestions remain reviewable and are not automatically dispatched to run.
- Add tests for validation, provider selection, mock invocation, purpose denial, redaction, and bridge integration.

**Non-Goals:**

- No real external provider network calls in tests or default local mode.
- No raw API key exposure to plugins, platform_web, run, logs, job payloads, or API responses.
- No automatic config write dispatch from AI output.
- No provider billing, agent-provider marketplace, cloud host sales, or unrelated SaaS workflows.

## Decisions

### Decision 1: Provider client is an interface with mock default for tests

The platform service owns provider selection and calls a narrow provider client interface. Tests and local verification use a deterministic fake provider client, while live provider clients can be added later behind the same interface.

Alternative considered: implement live OpenAI/Anthropic calls immediately. Rejected because this request must not require real keys/accounts or external paid services.

### Decision 2: AI purposes are mandatory

Every invocation request includes a purpose such as config recommendation, troubleshooting, log summary, or plugin assistant. Platform validation checks that the plugin and requested context allow that purpose before provider selection.

Alternative considered: infer purpose from prompt text. Rejected because permission checks need explicit reviewable inputs.

### Decision 3: Config outputs are recommendations, not writes

For config-related requests, responses may include a proposed diff or recommendation object. The caller must still use config preview/approval APIs before any run-side write occurs.

Alternative considered: let AI invocation directly queue config write jobs. Rejected because AI-suggested changes must be reviewable before dispatch.

### Decision 4: Redaction happens before persistence and response

Request metadata, prompts, provider errors, and responses are scanned for unsafe credential-like content before logging or returning to browser/plugin callers.

Alternative considered: rely on caller discipline and avoid scanning. Rejected because provider and prompt output can accidentally include sensitive-looking material.

## Risks / Trade-offs

- [Risk] Mock provider behavior can hide live provider quirks. Mitigation: keep provider interface small and add live integration in a separate opt-in change.
- [Risk] Purpose checks may reject useful flows. Mitigation: add new purposes through explicit manifest and OpenSpec updates.
- [Risk] AI output can be over-trusted by operators. Mitigation: config changes return reviewable diffs and never auto-dispatch.

## Migration Plan

1. Add platform invocation contracts, validators, provider client interface, service, routes, and tests.
2. Add frontend API client and plugin bridge request plumbing.
3. Add plugin SDK/example helpers and tests.
4. Update docs and run full verification.

Rollback removes invocation routes/provider interface integrations and this change's artifacts before plugin workflows depend on them.

## Open Questions

- Which live provider client should be implemented first after mock-mediated invocation passes?
- Which audit event schema should capture AI recommendation review and operator approval?