4.0 KiB
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
- Add platform invocation contracts, validators, provider client interface, service, routes, and tests.
- Add frontend API client and plugin bridge request plumbing.
- Add plugin SDK/example helpers and tests.
- 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?