browser/openspec/changes/implement-plugin-page-bridge-execution/design.md

Context

implement-plugin-bridge-and-sdk defines typed bridge envelopes and authorization decisions, but execution is still theoretical. This change makes plugin pages useful in the console by adding the host-side transport and backend execution adapter for allowed bridge actions. The platform remains authoritative: browser host checks improve UX, but backend validation decides whether a request can execute.

Goals / Non-Goals

Goals:

• Create safe plugin bridge sessions in platform_web from registry/page/server context.
• Dispatch plugin page bridge requests through centralized frontend API client methods.
• Add backend execution behavior for supported bridge actions by calling existing platform services instead of proxying arbitrary API paths.
• Return typed success/error envelopes to plugin pages.
• Add tests and browser walkthrough evidence for allowed actions, denied actions, and no secret exposure.

Non-Goals:

• No arbitrary HTTP proxy from plugin pages to platform APIs.
• No direct run sockets, host paths, raw credentials, auth storage, artifact storage credentials, or raw AI provider keys in plugin page context or responses.
• No iframe sandbox policy overhaul beyond what is necessary for bridge host execution.
• No package download, plugin marketplace commerce, billing, cloud host sales, or provider marketplace behavior.

Decisions

Decision 1: Backend execution uses an action switch over safe services

Bridge execution maps each supported action to a named backend service method, such as server context reads, job dispatch, log queries, artifact open/download metadata, scoped file dispatch, or platform-mediated AI invocation. Unsupported actions fail before side effects.

Alternative considered: accept a plugin-supplied URL/path and proxy it. Rejected because arbitrary proxying bypasses reviewable permission mapping.

Decision 2: Host context is short-lived and derived

The frontend host builds session context from selected server instance, plugin page metadata, safe theme tokens, and effective permissions. It does not persist platform auth tokens or raw backend state in plugin page-visible structures.

Alternative considered: pass the normal platform API client or auth storage into plugin pages. Rejected because plugin code is not a credential boundary.

Decision 3: Execution envelopes are typed and auditable

Every bridge execution request carries request ID, plugin ID, route key, action, server instance scope, purpose metadata, and bounded payload. Backend responses include allowed/denied state, typed result, and safe error details.

Alternative considered: reuse authorization-only DTOs for execution results. Rejected because execution needs result references and error details distinct from preflight authorization.

Risks / Trade-offs

• [Risk] Supported bridge action behavior depends on other platform capabilities. Mitigation: actions whose downstream service is not available return explicit unsupported/deferred errors and tests cover the available set.
• [Risk] Browser host checks can be bypassed. Mitigation: backend validation repeats all permission and safety checks.
• [Risk] Plugin page UI can create noisy request loops. Mitigation: host utilities include request bounds and cancellation/error state tests.

Migration Plan

1. Add bridge execution DTOs/domain/validators/services/routes in platform.
2. Add frontend host transport/API client/session utilities and tests.
3. Update plugin SDK/example tests to use execution envelopes.
4. Update docs and run full verification including browser walkthrough.

Rollback removes bridge execution routes, host transport utilities, SDK example changes, and this change's artifacts before downstream plugin pages depend on it.

Open Questions

• Which sandbox mechanism should eventually host third-party plugin page assets in production?
• Whether bridge execution audit events should be a separate observability change.