68 lines
4.0 KiB
Markdown
68 lines
4.0 KiB
Markdown
## 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?
|