browser/openspec/changes/implement-platform-mediated-ai-invocation/specs/platform-mediated-ai-invocation/spec.md

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