[jasper-yl]

Which issue or RFC does this PR close?

This PR proposes a follow-up RFC to RFC #2549 (plugin interfaces). It builds on the plugin host processes and the in-memory record of active plugins defined there. The plugin APIs and Dashboard pages are implemented in #2616.

Rationale for this change

RFC #2549 deliberately leaves out three things:

• Plugin changes require a Server restart.
• Plugins are reachable only through core's existing Source and Artifact APIs.
• Plugins have no way to upgrade the data an earlier version of them wrote.

Shared central deployments need to update plugins without downtime. Domain plugins such as document knowledge bases need their own operations (file upload, chunk editing, cross-base search and question answering) and their own pages, which do not fit core's generic APIs.

What changes are included in this PR?

New RFC docs/{en,zh}/rfcs/2579-plugin-reload-and-apis.md (Chinese first, English translation in sync):

• Hot reload:
  • Each Server process rescans the plugin directory every POWERCONTEXT_SERVER_PLUGINS_RESCAN_SECONDS (default 60 s, 0 disables). A directory is checked only after its content digest is the same in two consecutive scans.
  • Plugins are imported from read-only version snapshots named by content digest, so one call never mixes old and new code. Updates replace child processes only: a new host process starts from the new snapshot and the old one drains.
  • A failed update keeps the current version running; a new plugin that fails its check is not loaded.
• Plugin data upgrades: a plugin may provide upgrade(ctx), which core calls each time it loads a plugin version, before the version serves requests. The plugin decides whether and how to upgrade its data and stays compatible with old data itself; core records no data version and gives no fallback. The hook must be safe to repeat and to run on several instances at once.
• Plugin-defined APIs:
  • Declared routes mount at /v1/plugins/{name}/api{path} with access authenticated, scope.read, or scope.contribute (with scope_param). Core authenticates the caller; the host process checks Scope access and runs the handler.
  • Handlers confirm write access with the route's access or ctx.require, then use ctx.reads, ctx.writer, ctx.sources, and ctx.scopes as the caller. Writes in plugin APIs record no automatic provenance; to record who did what, a plugin submits the operation as a Source it defines and writes the revision in generate.
  • Routes may declare max_body_bytes under a deployment ceiling POWERCONTEXT_SERVER_PLUGIN_API_MAX_BODY_BYTES (default 32 MiB) that replaces the general HTTP body limit for plugin routes.
  • JSON routes can opt in as MCP tools (mcp=True). Per-plugin OpenAPI is served at /v1/plugins/{name}/openapi.json, outside the main contract.
• Plugin pages: static files shown in a sandboxed iframe (opaque origin, strict CSP). Pages call only their own plugin's routes, through postMessage forwarding by the Dashboard as the signed-in user, and never see the session cookie. Forwarding stops once the frame navigates away.
• Persistence: nothing new is persisted.

Are there any user-facing changes?

This PR changes documentation only. The proposed design adds plugin API routes, Dashboard plugin pages, MCP tools for opted-in routes, and two environment variables; it changes no existing API.

How was this change tested?

• uv run prek run --files docs/en/rfcs/2579-plugin-reload-and-apis.md docs/zh/rfcs/2579-plugin-reload-and-apis.md
• Checked that both locales have matching sections, tables, and code blocks.

AI usage statement

Drafted with Claude Code (Claude Opus 5.5) under the author's direction and review.

🤖 Generated with Claude Code

[hidb4ai]

The proposed reload and page-isolation mechanisms have reproducible gaps in their stated contracts. Details are inline; please address them in both language versions before accepting the RFC.

[hireview001]

LGTM

[hidb4ai]

The content digests and immutable snapshots address the previous reload findings. Explicitly allowing external access also supersedes the original form-submission finding. Two issues remain in the revised design: navigation can expose the authenticated forwarding bridge to an external document, and MCP tool names can collide. Please address both language versions.

[hidb4ai]

[P1] Bind forwarding to the original document before navigation completes

Waiting for the second iframe load is too late: scripts in the destination document run before that event. In a Chromium fixture implementing this rule, the plugin navigated to another local origin, whose script immediately posted a request for a declared plugin route while a slow image delayed load. The parent accepted it with loads === 1 and event.origin === "null", fetched the route with its HttpOnly; SameSite=Strict session cookie and Sec-Fetch-Site: same-origin, and returned the synthetic private response to the external document before disabling forwarding. The server-side checks therefore do not close this window. Bind requests and replies to a capability or message channel held only by the original document, rather than relying on the second load event and the frame's persistent WindowProxy identity.

[hidb4ai]

[P2] Make MCP tool identities unambiguous across routes and plugins

The prescribed name is not unique for otherwise valid declarations: plugin docs with handler search_all and plugin docs-search with handler all both become docs_search_all. The same plugin can also expose two distinct (method, path) routes using one handler, which produces the same collision. A tools/call with that name and identical arguments cannot select which route to execute, so at least one opted-in route is unreachable or resolves to the wrong operation. Define collision-free tool identities, or reject duplicate generated names across all active plugin and built-in tools before activation, including during hot reload.

[hidb4ai]

Re-reviewed 02089a8. The setup factory rename and ArtifactPlugin example updates leave both previously reported blockers unchanged: navigation can expose authenticated forwarding to an external document and generated MCP tool names can collide. The affected sections are unchanged in both locales, so the existing findings still apply to this head. Please address them in the original threads.