first commit

openspec/changes/implement-platform-mediated-ai-invocation/design.md

@@ -0,0 +1,67 @@
+## 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?